Vector Database

This endpoint group provides methods for interacting with the AppBuilder Vector Database, allowing you to store, update, delete, list, and semantically query vector embeddings associated with textual content. It delegates to the VectorDBManager for core logic.

Endpoints

POST /api/rpc (Method: VectorDBRpc.insert)

• Description: Inserts or updates points in the vector database for a given context.

• Request Body:

  {
    "method": "VectorDBRpc.insert",
    "params": {
      "contextKey": "yourProjectIdOrOtherContext",
      "points": [
        {
          "id": "point-uuid-1",
          "vector": [0.1, 0.2, 0.3, ...],
          "payload": {
            "content": "This is the main text content for embedding.",
            "metadata": {
              "author": "John Doe",
              "documentId": "doc-123"
            }
          }
        },
        {
          "id": 12345,
          "payload": {
            "content": "Another piece of content to be embedded automatically.",
            "metadata": {
              "category": "technical"
            }
          }
        }
      ]
    }
  }

• Parameters:

  Name	Type	Required	Description
  contextKey	String	Yes	The key defining the context/collection (e.g., projectId).
  points	Array<Object>	Yes	An array of points to insert/update. Each point requires an id and payload.content. Optionally, vector can be provided; otherwise, it will be generated from payload.content.
  points[].id	String (UUID) | Number (Integer)	Yes	Unique ID for the point.
  points[].vector	Array<Number>	No	Optional vector embedding. If not provided, it will be generated from payload.content.
  points[].payload	Object	Yes	Data associated with the vector.
  points[].payload.content	String	Yes	The main text content to be embedded and stored.
  points[].payload.metadata	Object	No	Optional additional metadata for the point (key-value pairs).

• Response:

  {
    "success": true,
    "data": {
      "success": true,
      "count": 2,
      "operation_time": 0.015
    }
  }

• Example (cURL):

  curl -X POST https://api.example.com/api/rpc \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "method": "VectorDBRpc.insert",
      "params": {
        "contextKey": "myAwesomeProject",
        "points": [
          {
            "id": "doc-a-123",
            "payload": {
              "content": "The quick brown fox jumps over the lazy dog.",
              "metadata": { "source": "example.txt" }
            }
          }
        ]
      }
    }'

POST /api/rpc (Method: VectorDBRpc.update)

• Description: Updates an existing point in the vector database.

• Request Body:

  {
    "method": "VectorDBRpc.update",
    "params": {
      "contextKey": "yourProjectIdOrOtherContext",
      "point": {
        "id": "point-uuid-1",
        "vector": [0.4, 0.5, 0.6, ...],
        "payload": {
          "content": "Updated content for the point.",
          "metadata": {
            "status": "reviewed"
          }
        }
      }
    }
  }

• Parameters:

  Name	Type	Required	Description
  contextKey	String	Yes	The key defining the context/collection.
  point	Object	Yes	The point data to update. Requires an id. vector or payload (or both) can be updated. If payload.content is provided and vector is not, the vector will be re-generated.
  point.id	String (UUID) | Number (Integer)	Yes	Unique ID for the point.
  point.vector	Array<Number>	No	Optional new vector embedding.
  point.payload	Object	No	New data associated with the vector.
  point.payload.content	String	No	The new main text content. If provided without vector, a new embedding will be generated.
  point.payload.metadata	Object	No	Optional additional metadata for the point (key-value pairs).

• Response:

  {
    "success": true,
    "data": {
      "success": true
    }
  }

• Example (cURL):

  curl -X POST https://api.example.com/api/rpc \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "method": "VectorDBRpc.update",
      "params": {
        "contextKey": "myAwesomeProject",
        "point": {
          "id": "doc-a-123",
          "payload": {
            "content": "The quick brown fox now jumps over the lazy dog faster.",
            "metadata": { "source": "example.txt", "version": 2 }
          }
        }
      }
    }'

POST /api/rpc (Method: VectorDBRpc.delete)

• Description: Deletes points from the vector database by their IDs.

• Request Body:

  {
    "method": "VectorDBRpc.delete",
    "params": {
      "contextKey": "yourProjectIdOrOtherContext",
      "pointIds": ["point-uuid-1", 12345]
    }
  }

• Parameters:

  Name	Type	Required	Description
  contextKey	String	Yes	The key defining the context/collection.
  pointIds	Array<String (UUID) | Number (Integer)>	Yes	An array of point IDs to delete.

• Response:

  {
    "success": true,
    "data": {
      "success": true
    }
  }

• Example (cURL):

  curl -X POST https://api.example.com/api/rpc \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "method": "VectorDBRpc.delete",
      "params": {
        "contextKey": "myAwesomeProject",
        "pointIds": ["doc-a-123"]
      }
    }'

POST /api/rpc (Method: VectorDBRpc.list)

• Description: Lists points from the vector database.

• Request Body:

  {
    "method": "VectorDBRpc.list",
    "params": {
      "contextKey": "yourProjectIdOrOtherContext",
      "limit": 20,
      "offset": "last-point-id-from-previous-page"
    }
  }

• Parameters:

  Name	Type	Required	Description
  contextKey	String	Yes	The key defining the context/collection.
  limit	Number (Integer)	No	The maximum number of points to return. Defaults to 10.
  offset	String (UUID) | Number (Integer)	No	The ID of the point to start listing from (for pagination).

• Response:

  {
    "success": true,
    "data": {
      "points": [
        {
          "id": "point-uuid-1",
          "payload": {
            "content": "This is the main text content.",
            "metadata": {
              "author": "John Doe"
            }
          }
        },
        {
          "id": 12345,
          "payload": {
            "content": "Another piece of content.",
            "metadata": {
              "category": "technical"
            }
          }
        }
      ],
      "next_page_offset": "next-point-id-for-pagination"
    }
  }

  The points array contains objects with id and payload. The payload includes the content and any metadata.

• Example (cURL):

  curl -X POST https://api.example.com/api/rpc \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "method": "VectorDBRpc.list",
      "params": {
        "contextKey": "myAwesomeProject",
        "limit": 5
      }
    }'

POST /api/rpc (Method: VectorDBRpc.query)

• Description: Performs a semantic query against the vector database.

• Request Body:

  {
    "method": "VectorDBRpc.query",
    "params": {
      "contextKey": "yourProjectIdOrOtherContext",
      "queryText": "documents about machine learning",
      "topK": 3,
      "filter": {
        "must": [
          {
            "key": "metadata.category",
            "match": {
              "value": "research"
            }
          }
        ]
      }
    }
  }

• Parameters:

  Name	Type	Required	Description
  contextKey	String	Yes	The key defining the context/collection.
  queryText	String	Yes	The text to semantically query. An embedding will be generated from this text.
  topK	Number (Integer)	No	The maximum number of top similar results to return. Defaults to 5.
  filter	Object	No	An optional filter object to apply to the search (e.g., for metadata filtering).

• Response:

  {
    "success": true,
    "data": [
      {
        "id": "point-uuid-A",
        "payload": {
          "content": "Content related to machine learning and AI.",
          "metadata": {
            "category": "research"
          }
        },
        "vector": [...],
        "score": 0.987
      },
      {
        "id": "point-uuid-B",
        "payload": {
          "content": "Another document on deep learning algorithms.",
          "metadata": {
            "category": "research"
          }
        },
        "vector": [...],
        "score": 0.950
      }
    ]
  }

  The response is an array of search results, each containing the id, payload (including content and metadata), the vector of the found point, and a score indicating similarity to the query.

• Example (cURL):

  curl -X POST https://api.example.com/api/rpc \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "method": "VectorDBRpc.query",
      "params": {
        "contextKey": "myAwesomeProject",
        "queryText": "latest advancements in quantum computing",
        "topK": 2
      }
    }'