Vector Upsert

The core function of an upsert is its atomicity. The database performs a single, indivisible operation: it checks for an existing vector with the provided unique ID. If found, it updates that record with the new vector and metadata. If not found, it inserts a new record. This eliminates race conditions that could occur with separate insert and update calls.

Upsert operations are inherently idempotent. Making the same upsert request with the same ID multiple times will leave the database in the same final state as making it once. This property is critical for building reliable data pipelines, as it allows for safe retries of failed requests without causing duplicates or errors.

• Safe Retries: Network timeouts or transient errors can be retried automatically.
• Simplified Logic: Clients don't need complex "check-then-insert/update" logic.

A vector upsert synchronizes both the high-dimensional embedding and its associated metadata in a single transaction. The metadata is typically stored in a structured format (like JSON) and is used for filtered search.

• Example: Upserting a product vector might update both its image embedding and metadata fields like price, category, and in_stock status simultaneously.
• Consistency: This ensures the semantic meaning (vector) and its factual attributes (metadata) are always aligned.

After an upsert, the underlying vector index (e.g., HNSW, IVF) must be updated to reflect the new or modified data point. The behavior depends on the index type and database implementation:

• Incremental Updates: Some graph-based indexes (HNSW) can add or update nodes dynamically with minimal disruption.
• Background Reindexing: Other indexes may flag the change and incorporate it into a background optimization job.
• Query Consistency: The database manages when the updated vector becomes visible to subsequent nearest neighbor queries.

The request and response payloads for an upsert are distinct from pure insert or update calls.

• Request Payload: Must include the mandatory id and vector fields, with optional metadata.
• Response: Typically indicates success and may return the assigned ID. It usually does not distinguish between an insert and an update action to preserve idempotency.
• Error Handling: Specific errors can include invalid vector dimensions, duplicate ID conflicts on pure-insert modes, or schema violations for metadata.

For high-volume updates, upsert operations are often supported in batch mode. A batch upsert API accepts an array of vectors/IDs/metadata in a single request, dramatically increasing throughput and reducing network overhead.

• Performance: Batch operations are optimized internally, reducing per-request processing costs.
• Atomicity per Batch: The entire batch may be applied atomically, or each item may be processed independently with partial success semantics.
• Use Case: Essential for continuous model learning systems where embeddings are regularly refreshed from updated source data.

A Batch API allows for submitting multiple vector upsert operations (or other commands like deletes) in a single network request. This dramatically improves data ingestion throughput and reduces latency compared to sequential single requests. Batch operations are atomic in many systems, meaning all upserts succeed or fail together, ensuring data consistency.

• Use Case: Initial bulk loading of an embedding dataset or periodic batch updates from an ETL pipeline.

An Async API provides non-blocking endpoints for long-running operations. For a high-volume vector upsert job, a client can submit the request and receive an immediate acknowledgment or job ID, then poll for completion or receive a callback via webhook. This prevents clients from blocking while waiting for millions of vectors to be indexed and is crucial for building responsive applications that handle large data updates.

The Collection API manages logical containers (collections) that hold vectors and their metadata. A vector upsert operation always targets a specific collection. This API handles:

• Creating and deleting collections.
• Configuring collection parameters like vector dimension, distance metric, and index type.
• Retrieving collection statistics (e.g., vector count). It provides the organizational structure necessary for multi-tenant or multi-dataset scenarios.

A Client SDK is a language-specific library (e.g., for Python, JavaScript, Go) that abstracts the raw HTTP calls of a vector database's REST or gRPC API. It provides a simplified, idiomatic interface for developers to execute vector upsert and other operations. Key features include:

• Connection pooling for performance.
• Built-in retry logic and circuit breaker patterns for resilience.
• Native data type serialization (e.g., NumPy arrays).

An Embedding API is a service that converts raw data (text, images) into vector representations. It is often a prerequisite step before a vector upsert. While some vector databases offer integrated embedding models, others rely on external services (e.g., OpenAI, Cohere). The upsert pipeline typically involves: 1) Calling the Embedding API to generate vectors, 2) Packaging vectors with IDs and metadata, 3) Calling the vector database's upsert endpoint.