> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lambdadb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsert data

> Insert or update documents in a LambdaDB collection using the upsert operation. Includes Python, TypeScript, Go, and cURL code examples.

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](https://docs.lambdadb.ai/guides/data-versioning/branches-tags-aliases.md#create-and-list-branches), 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. The dense examples use synthetic 64-dimensional vectors; configure `dense_vector` with `dimensions: 64`. For real data, send the full vectors from your embedding model, matching the field's dimensions within the [supported range](https://docs.lambdadb.ai/guides/get-started/limits.md#collections-and-schema).

> [!NOTE]
>
> If the collection contains native embedding vector fields, send the configured source fields and LambdaDB generates the vector. A directly supplied vector is stored as is and skips inference. See [Native embedding write behavior](https://docs.lambdadb.ai/guides/collections/native-embeddings.md#write-behavior).

```python Python theme={null}
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 a serverless search database ... ", "dense_vector": [(i + 1) / 64 for i in range(64)], "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": [(i + 11) / 64 for i in range(64)], "sparse_vector": {"0": 0.8, "4": 0.1, "11": 0.1, "63": 0.54}},
    ]
    coll.docs.upsert(docs=docs)
```

> [!NOTE]
>
> 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.

```typescript TypeScript theme={null}
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 a serverless search database ... ", dense_vector: Array.from({ length: 64 }, (_, i) => (i + 1) / 64), 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: Array.from({ length: 64 }, (_, i) => (i + 11) / 64), sparse_vector: { "0": 0.8, "4": 0.1, "11": 0.1, "63": 0.54 } },
  ],
});
```

```go Go theme={null}
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")
  demoVector := func(offset int) []float64 {
    values := make([]float64, 64)
    for i := range values { values[i] = float64(i + offset) / 64 }
    return values
  }
  myDocs := []map[string]interface{}{
    {"id": "33201222", "url": "https://en.wikipedia.org/wiki/LambdaDB", "title": "LambdaDB", "text": "LambdaDB is a serverless search database ... ", "dense_vector": demoVector(1), "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": demoVector(11)},
  }
  _, err := coll.Docs().Upsert(ctx, lambdadb.UpsertDocsInput{Docs: myDocs})
  if err != nil {
    log.Fatal(err)
  }
}
```

```bash cURL theme={null}
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 a serverless search database ... ",
        "dense_vector": [
          0.015625, 0.03125, 0.046875, 0.0625, 0.078125, 0.09375, 0.109375, 0.125,
          0.140625, 0.15625, 0.171875, 0.1875, 0.203125, 0.21875, 0.234375, 0.25,
          0.265625, 0.28125, 0.296875, 0.3125, 0.328125, 0.34375, 0.359375, 0.375,
          0.390625, 0.40625, 0.421875, 0.4375, 0.453125, 0.46875, 0.484375, 0.5,
          0.515625, 0.53125, 0.546875, 0.5625, 0.578125, 0.59375, 0.609375, 0.625,
          0.640625, 0.65625, 0.671875, 0.6875, 0.703125, 0.71875, 0.734375, 0.75,
          0.765625, 0.78125, 0.796875, 0.8125, 0.828125, 0.84375, 0.859375, 0.875,
          0.890625, 0.90625, 0.921875, 0.9375, 0.953125, 0.96875, 0.984375, 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": [
          0.171875, 0.1875, 0.203125, 0.21875, 0.234375, 0.25, 0.265625, 0.28125,
          0.296875, 0.3125, 0.328125, 0.34375, 0.359375, 0.375, 0.390625, 0.40625,
          0.421875, 0.4375, 0.453125, 0.46875, 0.484375, 0.5, 0.515625, 0.53125,
          0.546875, 0.5625, 0.578125, 0.59375, 0.609375, 0.625, 0.640625, 0.65625,
          0.671875, 0.6875, 0.703125, 0.71875, 0.734375, 0.75, 0.765625, 0.78125,
          0.796875, 0.8125, 0.828125, 0.84375, 0.859375, 0.875, 0.890625, 0.90625,
          0.921875, 0.9375, 0.953125, 0.96875, 0.984375, 1.0, 1.015625, 1.03125,
          1.046875, 1.0625, 1.078125, 1.09375, 1.109375, 1.125, 1.140625, 1.15625
        ],
        "sparse_vector" : {"0": 0.8, "4": 0.1, "11": 0.1, "63": 0.54}
      }
    ]
  }'
```

## Response

```json theme={null}
{
  "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](https://docs.lambdadb.ai/guides/documents/fetch-data.md) 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](https://docs.lambdadb.ai/reference/api/introduction.md#errors-and-retries).

> [!NOTE]
>
> For a partitioned collection, documents are upserted into the `__default__` partition if the partition field is not provided.

## Upsert limits

See [request and document limits](https://docs.lambdadb.ai/guides/get-started/limits.md#requests-and-documents) for request size, document size, and ID length, and [schema limits](https://docs.lambdadb.ai/guides/get-started/limits.md#collections-and-schema) for vector dimensions.

When upserting larger amounts of data, it is recommended to use
[bulk-upsert](https://docs.lambdadb.ai/guides/documents/bulk-upsert-data.md) operation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.