Upsert data

This page shows you how to upsert documents into a collection. The examples write to the default branch, main. The REST request accepts an optional branch field. To write to another branch, create it first, then include its name in branch; a tag or alias is not a valid write target. Document field names are preserved as supplied in every SDK. The examples use dense_vector and sparse_vector; configure indexes with those same names to search these values.

If the collection contains native embedding vector fields, send only the configured source text fields. Do not send direct vector values for native embedding fields in an upsert request.

from lambdadb import LambdaDB

with LambdaDB(
    project_api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL",
    project_name="YOUR_PROJECT_NAME",
) as client:
    coll = client.collection("my_collection")
    docs = [
        {"id": "33201222", "url": "https://en.wikipedia.org/wiki/LambdaDB", "title": "LambdaDB", "text": "LambdaDB is the vector lake for AI memory ... ", "dense_vector": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0], "sparse_vector": {"LambdaDB": 0.83, "is": 0.1, "a": 0.1, "AI": 0.7}},
        {"id": "33201223", "url": "https://en.wikipedia.org/wiki/Winamp", "title": "Winamp", "text": "Winamp is a media player for Windows, macOS and Android ...", "dense_vector": [1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.0], "sparse_vector": {"0": 0.8, "4": 0.1, "11": 0.1, "63": 0.54}},
    ]
    coll.docs.upsert(docs=docs)

Python: LambdaDB supports context manager usage. __enter__ returns the client, and __exit__ calls client.close() (closing the SDK-owned HTTP client) and makes the client unusable after the with block. If you don’t use with, call client.close() when you’re done. If you pass a custom client=/async_client=, you own closing it.

import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  projectApiKey: "YOUR_API_KEY",
  baseUrl: "YOUR_BASE_URL",
  projectName: "YOUR_PROJECT_NAME",
});
const collection = client.collection("my_collection");
await collection.docs.upsert({
  docs: [
    { id: "33201222", url: "https://en.wikipedia.org/wiki/LambdaDB", title: "LambdaDB", text: "LambdaDB is the vector lake for AI memory ... ", dense_vector: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0], sparse_vector: { LambdaDB: 0.83, is: 0.1, a: 0.1, AI: 0.7 } },
    { id: "33201223", url: "https://en.wikipedia.org/wiki/Winamp", title: "Winamp", text: "Winamp is a media player for Windows, macOS and Android ...", dense_vector: [1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.0], sparse_vector: { "0": 0.8, "4": 0.1, "11": 0.1, "63": 0.54 } },
  ],
});

package main

import (
  "context"
  "log"
  lambdadb "github.com/lambdadb/go-lambdadb"
)

func main() {
  ctx := context.Background()
  client := lambdadb.New(
    lambdadb.WithBaseURL("YOUR_BASE_URL"),
    lambdadb.WithProjectName("YOUR_PROJECT_NAME"),
    lambdadb.WithAPIKey("YOUR_API_KEY"),
  )
  coll := client.Collection("my_collection")
  myDocs := []map[string]interface{}{
    {"id": "33201222", "url": "https://en.wikipedia.org/wiki/LambdaDB", "title": "LambdaDB", "text": "LambdaDB is the vector lake for AI memory ... ", "dense_vector": []float64{0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0}, "sparse_vector": map[string]float64{"LambdaDB": 0.83, "is": 0.1, "a": 0.1, "AI": 0.7}},
    {"id": "33201223", "url": "https://en.wikipedia.org/wiki/Winamp", "title": "Winamp", "text": "Winamp is a media player for Windows, macOS and Android ...", "dense_vector": []float64{1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.0}},
  }
  _, err := coll.Docs().Upsert(ctx, lambdadb.UpsertDocsInput{Docs: myDocs})
  if err != nil {
    log.Fatal(err)
  }
}

BASE_URL="YOUR_BASE_URL"
PROJECT_NAME="YOUR_PROJECT_NAME"
COLLECTION_NAME="my_collection"
LAMBDADB_PROJECT_API_KEY="YOUR_API_KEY"

curl -X POST \
  "$BASE_URL/projects/$PROJECT_NAME/collections/$COLLECTION_NAME/docs/upsert" \
  -H 'content-type: application/json' \
  -H "x-api-key: $LAMBDADB_PROJECT_API_KEY" \
  -d '{
    "docs": [
      {
        "id": "33201222",
        "url": "https://en.wikipedia.org/wiki/LambdaDB",
        "title": "LambdaDB",
        "text": "LambdaDB is the vector lake for AI memory ... ",
        "dense_vector" : [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0],
        "sparse_vector" : {"LambdaDB": 0.83, "is": 0.1, "a": 0.1, "AI": 0.7}
      },
      {
        "id": "33201223",
        "url": "https://en.wikipedia.org/wiki/Winamp",
        "title": "Winamp",
        "text": "Winamp is a media player for Windows, macOS and Android ...",
        "dense_vector" : [1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.0],
        "sparse_vector" : {"0": 0.8, "4": 0.1, "11": 0.1, "63": 0.54}
      }
    ]
  }'

Response

{
  "message": "Upsert request is accepted"
}

Each document implicitly contains an id field in order to uniquely identify a document. A unique string value is auto-generated by the system if id field is not provided in an upsert request. If you want to overwrite the entire document, you can do so by providing the id field in the document.

IDs and retries

The acceptance response does not return auto-generated IDs. If you need to fetch, update, delete, or retry a document later, assign its ID before sending the request. Repeating an upsert without an ID can create another document with a new ID. Keep the same ID, branch, and partition-field value when replaying a write. An upsert replaces the entire document at that identity, so replaying an older payload can overwrite newer changes. Stable IDs prevent duplicate identities; they do not make writes conditional on the current document version. If a request times out or the connection closes after dispatch, its outcome may be unknown. Fetch the expected IDs from the same branch with consistentRead: true and, for a partitioned collection, a partitionFilter selecting the original partition. Compare the stored content with the intended payload before deciding whether a retry is still needed. Do not infer write failure from an empty eventually consistent result. If that verification also fails, retain the unknown outcome and use the error-specific retry guidance.

For a partitioned collection, documents are upserted into the __default__ partition if the partition field is not provided.

Upsert limits

Metric	Limit
Max payload size	6MB
Max length for a document ID	512 characters
Max vector dimensions	4,096
Max document size	5MB

When upserting larger amounts of data, it is recommended to use bulk-upsert operation.

Get started

Migrations

Collections

Data versioning

Documents

Search

Manage Costs

Security

Response

IDs and retries

Upsert limits

​Response

​IDs and retries

​Upsert limits

Response

IDs and retries

Upsert limits