Upsert Documents

upsert() works similar to insert() — it adds one or more new documents (Doc) to a collection.

The key difference is that if a document with the same id already exists, it will be overwritten.

Use upsert() if you want to overwrite an existing document (or don't mind replacing it).
Use insert() if you want to avoid accidentally overwriting a document — insert() will fail if a document with the same id already exists.

Performance Tip:
New vectors are initially buffered for fast ingestion. For optimal search performance, call optimize() after upserting a large batch of documents.

Document `Doc`

Each Doc passed to upsert() must:

Have an id (if a document with the same id already exists, it will be replaced)
Provide data that matches the collection's schema:
1. Scalar fields: provided as key–value pairs under fields (scalar field names as keys)
2. Vector embeddings: provided as key–value pairs under vectors (vector names as keys)
You can omit nullable scalar fields if a document doesn't have a value for them

Upsert a Single Document

Assume you already have a collection with the following schema:

A scalar field: text (string)
A dense vector embedding: text_embedding (4-dimensional FP32 vector)
The 4-dimensional vector is for demonstration only — real-world embeddings are usually much larger.

You've also opened the collection and have a collection object ready.

Now, upsert a document like this:

Upsert a document

import zvec

# Create a document
doc = zvec.Doc(  
    id="text_1",  # ← must be unique
    vectors={
        "text_embedding": [0.1, 0.2, 0.3, 0.4],  # ← must match the vector name
                          # ↑ list of floats; list length = dimension (4)
    },
    fields={
        "text": "This is a sample text.",  # ← must match the scalar field name
    },
)

# Upsert the document
result = collection.upsert(doc)  
print(result)  # {"code": 0} means success

The upsert() method validates the document first:

Incorrect usage — such as an unknown field or wrong vector dimension — raises an exception.
If validation passes, the method proceeds with the upsertion and returns a Status object:
- {"code": 0} indicates success.
- Non-zero codes indicate failure (e.g., insufficient disk space).

Successfully upserted documents are immediately available for querying 🚀.

Upsert a document

import { ZVecCollection, ZVecDocInput, ZVecOpen } from "@zvec/zvec";

// Create a document
let doc: ZVecDocInput = { 
    id: "text_1",   // ← must be unique
    vectors: {
        "text_embedding": [0.1, 0.2, 0.3, 0.4]  // ← must match the vector name
                          // ↑ list of floats; list length = dimension (4)
    },
    fields: {
        "text": "This is a sample text."    // ← must match the scalar field name
    }
};

// Upsert the document
let result = collection.upsertSync(doc);  
console.log(result);  // { ok: true } means success

The upsert() method validates the document first:

Incorrect usage — such as an unknown field or wrong vector dimension — raises an exception.
If validation passes, the method proceeds with the upsertion and returns a Status object:
- { ok: true } indicates success.
- { ok: false } indicates failure (e.g., insufficient disk space).

Successfully upserted documents are immediately available for querying 🚀.

Upsert a Batch of Documents

To upsert multiple documents at once, pass a list of Doc objects to upsert().
Each Doc is processed independently, and the method returns a list of Status objects — one per document.

Upsert a batch of documents

import zvec

result = collection.upsert(  
    [
        zvec.Doc(
            id="text_1",
            vectors={"text_embedding": [0.1, 0.2, 0.3, 0.4]},
            fields={"text": "This is a sample text."},
        ),
        zvec.Doc(
            id="text_2",
            vectors={"text_embedding": [0.4, 0.3, 0.2, 0.1]},
            fields={"text": "This is another sample text."},
        ),
        zvec.Doc(
            id="text_3",
            vectors={"text_embedding": [-0.1, -0.2, -0.3, -0.4]},
            fields={"text": "One more sample text."},
        ),
    ]
)

print(result)  # [{"code":0}, {"code":0}, {"code":0}]

If any document in the batch has incorrect usage (e.g., an unknown field or wrong vector dimension), the method raises an exception and no documents are upserted.

If all documents are valid, the method attempts to upsert every one. A failure in one (e.g., insufficient disk space) does not stop others from being upserted.

🔍 Always check each Status in the result list.