Request Payload

The payload's root object specifies the action to be performed. Common operations include:

• upsert: Insert new vectors or update existing ones by ID.
• query: Perform a similarity search for nearest neighbors.
• delete: Remove vectors by ID or using a filter.
• fetch: Retrieve vectors and metadata by their IDs. Each operation type has a distinct required schema for its accompanying parameters.

This is the core data for upsert and the target for query operations.

• Vectors: A list of high-dimensional floating-point arrays (embeddings). For an upsert, this is the data to store. For a query, this is the search vector.
• IDs: A unique identifier (string or integer) for each vector during upsert, allowing for later updates, fetches, or deletions. In a query payload, the vector is provided without an ID.

Optional structured data associated with each vector, enabling hybrid search.

• Stored as key-value pairs (e.g., {"category": "document", "author": "Jane Doe", "timestamp": 1710432000}).
• Used in filter expressions during queries to scope similarity search results (e.g., category == 'document' AND author != 'Admin').
• Typically indexed separately from vectors for fast filtering.

Critical for query operations, these parameters control the search's behavior and quality.

• top_k or limit: The maximum number of nearest neighbors to return.
• distance_metric: The function used to measure similarity (e.g., cosine, euclidean, dot_product). Must match the index configuration.
• include_metadata / include_values: Flags controlling whether the full vector data and metadata are returned in the response.

A Boolean expression applied to vector metadata to pre-filter the search space before or after the vector similarity calculation.

• Syntax is often similar to SQL WHERE clauses (e.g., price <= 50.0 AND status == 'in_stock').
• Enables precise, context-aware retrieval by combining semantic meaning with hard business rules.
• Execution can be pre-filter (slower, more accurate) or post-filter (faster, may reduce recall).

A logical partition or grouping within the database. Specifying this in the payload isolates operations to a specific subset of vectors.

• Acts like a table in a relational database or an index in a search engine.
• Allows for multi-tenancy or organization of data by domain (e.g., products, user_profiles, support_docs).
• Must be specified in most payloads to direct the operation to the correct data partition.

An API Endpoint is the specific URL where a client sends a request to interact with a particular function of a vector database. It defines the location and the intended operation.

• Structure: Follows a resource-oriented path, e.g., POST /v1/collections/{id}/vectors for an insert operation.
• HTTP Method: The endpoint is paired with an HTTP method (GET, POST, PUT, DELETE) that defines the action.
• Purpose: The endpoint and method together tell the server what to do, while the request payload provides the data for that operation.

HTTP Headers are key-value pairs sent at the start of an API request (and response) that convey metadata about the transaction. They are separate from the request payload body.

• Authentication: Headers like Authorization: Bearer <API_KEY> are used for secure access control.
• Content Definition: The Content-Type: application/json header informs the server that the request payload is formatted as JSON.
• Control Metadata: Headers can specify API version (Accept: application/vnd.api.v1+json), enable compression (Accept-Encoding: gzip), or manage caching.

The Response Payload is the data returned by the vector database server in the body of the HTTP response, sent after processing the request. It is the counterpart to the request payload.

• Success Responses: Typically contain the requested data, such as an array of nearest neighbor search results with vectors, IDs, distances, and metadata.
• Error Responses: Contain structured error information (e.g., {"code": 404, "message": "Collection not found"}) when a request fails.
• Structure: Like request payloads, these are commonly formatted in JSON and defined by the API's schema.

Idempotency is a property of an API operation where making the same identical request (including its payload) multiple times has the same effect as making it once. This is crucial for reliable retries.

• Importance for Payloads: Prevents duplicate vector inserts if a network timeout causes a client to retry. An idempotent POST with a unique ID will create the vector once; subsequent retries will not create duplicates.
• Implementation: Often achieved by requiring a client-supplied unique ID (e.g., vector_id) in the request payload or by using idempotency keys in HTTP headers.
• Safe Methods: GET, PUT, and DELETE are inherently idempotent; POST operations require design to become idempotent.

Serialization Format refers to the standard used to encode the structured data in a request or response payload into a byte stream for transmission. JSON is the most common format for RESTful vector database APIs.

• JSON (JavaScript Object Notation): Human-readable, text-based format. A vector insert payload is serialized as: {"vectors": [{"id": "vec_1", "values": [0.1, 0.2, ...], "metadata": {"category": "docs"}}]}.
• Protocol Buffers (Protobuf): Used by gRPC APIs. A binary, schema-driven format that is more compact and faster to serialize/deserialize than JSON, reducing payload size and latency.
• Content-Type Header: Specifies the format (e.g., application/json, application/protobuf) so the server knows how to deserialize the payload.

A Batch API is an interface that allows multiple discrete operations to be bundled into a single request payload. This optimizes throughput and reduces network overhead for bulk data operations.

• Payload Structure: The request body contains an array of operations, such as multiple insert or delete commands.
• Efficiency: Significantly reduces the number of HTTP connections and round trips compared to sending individual requests for each vector.
• Use Case: Ideal for initial bulk ingestion of embeddings or for applying bulk metadata updates. The server processes the batch as a single transactional unit or in an optimized sequence.