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

# Add Items to an Encrypted Index

Once you have created or connected to an encrypted index, you can add items to it. To do this, you can use the `upsert()` function:

<CodeGroup>
  ```python Python SDK icon="python" theme={null}
  # Items to add to the encrypted index
  items = [
      {"id": "item_1", "vector": [0.1, 0.2, 0.3, 0.4]},
      {"id": "item_2", "vector": [0.5, 0.6, 0.7, 0.8]},
      {"id": "item_3", "vector": [0.9, 0.10, 0.11, 0.12]}
  ]

  # Add items to the encrypted index
  index.upsert(items)
  ```

  ```javascript JavaScript SDK icon="js" theme={null}
  // Items to add to the encrypted index
  const items = [
      {id: "item_1", vector: [0.1, 0.2, 0.3, 0.4]},
      {id: "item_2", vector: [0.5, 0.6, 0.7, 0.8]},
      {id: "item_3", vector: [0.9, 0.10, 0.11, 0.12]}
  ];

  // Add items to the encrypted index
  await index.upsert({ items });
  ```

  ```typescript TypeScript SDK icon="code" theme={null}
  import { VectorItem, UpsertRequest } from 'cyborgdb';

  // Items to add to the encrypted index
  const items: VectorItem[] = [
      {id: "item_1", vector: [0.1, 0.2, 0.3, 0.4]},
      {id: "item_2", vector: [0.5, 0.6, 0.7, 0.8]},
      {id: "item_3", vector: [0.9, 0.10, 0.11, 0.12]}
  ];

  // Add items to the encrypted index
  const params: UpsertRequest = { items };
  await index.upsert(params);
  ```

  ```go Go SDK icon="golang" theme={null}
  package main

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

  // Items to add to the encrypted index
  items := cyborgdb.VectorItems{
      {Id: "item_1", Vector: []float32{0.1, 0.2, 0.3, 0.4}},
      {Id: "item_2", Vector: []float32{0.5, 0.6, 0.7, 0.8}},
      {Id: "item_3", Vector: []float32{0.9, 0.10, 0.11, 0.12}},
  }

  // Add items to the encrypted index
  err := index.Upsert(context.Background(), items)
  if err != nil {
      log.Fatal(err)
  }
  ```

  ```bash cURL icon="rectangle-terminal" theme={null}
  curl -X POST "http://localhost:8000/v1/vectors/upsert" \
       -H "X-API-Key: your-api-key" \
       -H "Content-Type: application/json" \
       -d '{
         "index_name": "my_index",
         "index_key": "your_64_character_hex_key_here",
         "items": [
           {
             "id": "item_1",
             "vector": [0.1, 0.2, 0.3, 0.4]
           },
           {
             "id": "item_2", 
             "vector": [0.5, 0.6, 0.7, 0.8]
           },
           {
             "id": "item_3",
             "vector": [0.9, 0.10, 0.11, 0.12]
           }
         ]
       }'
  ```
</CodeGroup>

## Adding Items with Contents

It's also possible to store item contents alongside vectors. To do this, include `contents` in the `upsert()` call.

The contents field accepts both strings and bytes. Bytes are automatically base64-encoded before encryption, while strings are passed as-is. All contents are encrypted before storage using the index key. In Python, contents are returned in their original format (string or bytes) when retrieved with `get()`. In JavaScript/TypeScript, contents are returned as decoded UTF-8 strings. In Go, contents are returned as string.

<CodeGroup>
  ```python Python SDK icon="python" theme={null}
  # Items to add to the encrypted index
  items = [
      {"id": "item_1", "vector": [0.1, 0.2, 0.3, 0.4], "contents": "Hello!"},
      {"id": "item_2", "vector": [0.5, 0.6, 0.7, 0.8], "contents": "World!"},
      {"id": "item_3", "vector": [0.9, 0.10, 0.11, 0.12], "contents": "Cyborg!"}
  ]

  # Add items to the encrypted index
  index.upsert(items)
  ```

  ```javascript JavaScript SDK icon="js" theme={null}
  // Items to add to the encrypted index
  const items = [
      {id: "item_1", vector: [0.1, 0.2, 0.3, 0.4], contents: "Hello!"},
      {id: "item_2", vector: [0.5, 0.6, 0.7, 0.8], contents: "World!"},
      {id: "item_3", vector: [0.9, 0.10, 0.11, 0.12], contents: "Cyborg!"}
  ];

  // Add items to the encrypted index
  await index.upsert({ items });
  ```

  ```typescript TypeScript SDK icon="code" theme={null}
  import { VectorItem, UpsertRequest } from 'cyborgdb';

  // Items to add to the encrypted index
  const items: VectorItem[] = [
      {id: "item_1", vector: [0.1, 0.2, 0.3, 0.4], contents: "Hello!"},
      {id: "item_2", vector: [0.5, 0.6, 0.7, 0.8], contents: "World!"},
      {id: "item_3", vector: [0.9, 0.10, 0.11, 0.12], contents: "Cyborg!"}
  ];

  // Add items to the encrypted index
  const params: UpsertRequest = { items };
  await index.upsert(params);
  ```

  ```go Go SDK icon="golang" theme={null}
  // Items to add to the encrypted index
  items := cyborgdb.VectorItems{
      {Id: "item_1", Vector: []float32{0.1, 0.2, 0.3, 0.4}, Contents: cyborgdb.NewNullableContents("Hello!")},
      {Id: "item_2", Vector: []float32{0.5, 0.6, 0.7, 0.8}, Contents: cyborgdb.NewNullableContents("World!")},
      {Id: "item_3", Vector: []float32{0.9, 0.10, 0.11, 0.12}, Contents: cyborgdb.NewNullableContents("Cyborg!")},
  }

  // Add items to the encrypted index
  err := index.Upsert(context.Background(), items)
  if err != nil {
      log.Fatal(err)
  }
  ```

  ```bash cURL icon="rectangle-terminal" theme={null}
  curl -X POST "http://localhost:8000/v1/vectors/upsert" \
       -H "X-API-Key: your-api-key" \
       -H "Content-Type: application/json" \
       -d '{
         "index_name": "my_index",
         "index_key": "your_64_character_hex_key_here",
         "items": [
           {
             "id": "item_1",
             "vector": [0.1, 0.2, 0.3, 0.4],
             "contents": "Hello!"
           },
           {
             "id": "item_2",
             "vector": [0.5, 0.6, 0.7, 0.8], 
             "contents": "World!"
           },
           {
             "id": "item_3",
             "vector": [0.9, 0.10, 0.11, 0.12],
             "contents": "Cyborg!"
           }
         ]
       }'
  ```
</CodeGroup>

## Adding Items with Metadata

CyborgDB also supports metadata storage, retrieval and filtering. To add metadata to an item, include `metadata` in the `upsert()` call.

All metadata fields will be encrypted using the index key.

<CodeGroup>
  ```python Python SDK icon="python" theme={null}
  # Items to add to the encrypted index
  items = [
      {"id": "item_1", "vector": [0.1, 0.2, 0.3, 0.4], "metadata": {"name": "Alice", "age": 30}},
      {"id": "item_2", "vector": [0.5, 0.6, 0.7, 0.8], "metadata": {"name": "Bob", "age": 40}},
      {"id": "item_3", "vector": [0.9, 0.10, 0.11, 0.12], "metadata": {"name": "Charlie", "age": 50}}
  ]

  # Add items to the encrypted index
  index.upsert(items)
  ```

  ```go Go SDK icon="golang" theme={null}
  // Items to add to the encrypted index
  items := cyborgdb.VectorItems{
      {
          Id: "item_1", 
          Vector: []float32{0.1, 0.2, 0.3, 0.4}, 
          Metadata: map[string]interface{}{"name": "Alice", "age": 30},
      },
      {
          Id: "item_2", 
          Vector: []float32{0.5, 0.6, 0.7, 0.8}, 
          Metadata: map[string]interface{}{"name": "Bob", "age": 40},
      },
      {
          Id: "item_3", 
          Vector: []float32{0.9, 0.10, 0.11, 0.12}, 
          Metadata: map[string]interface{}{"name": "Charlie", "age": 50},
      },
  }

  // Add items to the encrypted index
  err := index.Upsert(context.Background(), items)
  if err != nil {
      log.Fatal(err)
  }
  ```

  ```javascript JavaScript SDK icon="js" theme={null}
  // Items to add to the encrypted index
  const items = [
      {id: "item_1", vector: [0.1, 0.2, 0.3, 0.4], metadata: {name: "Alice", age: 30}},
      {id: "item_2", vector: [0.5, 0.6, 0.7, 0.8], metadata: {name: "Bob", age: 40}},
      {id: "item_3", vector: [0.9, 0.10, 0.11, 0.12], metadata: {name: "Charlie", age: 50}}
  ];

  // Add items to the encrypted index
  await index.upsert({ items });
  ```

  ```typescript TypeScript SDK icon="code" theme={null}
  import { VectorItem, UpsertRequest } from 'cyborgdb';

  // Define metadata type (optional)
  interface PersonMetadata {
      name: string;
      age: number;
  }

  // Items to add to the encrypted index
  const items: VectorItem[] = [
      {id: "item_1", vector: [0.1, 0.2, 0.3, 0.4], metadata: {name: "Alice", age: 30} as PersonMetadata},
      {id: "item_2", vector: [0.5, 0.6, 0.7, 0.8], metadata: {name: "Bob", age: 40} as PersonMetadata},
      {id: "item_3", vector: [0.9, 0.10, 0.11, 0.12], metadata: {name: "Charlie", age: 50} as PersonMetadata}
  ];

  // Add items to the encrypted index
  const params: UpsertRequest = { items };
  await index.upsert(params);
  ```

  ```bash cURL icon="rectangle-terminal" theme={null}
  curl -X POST "http://localhost:8000/v1/vectors/upsert" \
       -H "X-API-Key: your-api-key" \
       -H "Content-Type: application/json" \
       -d '{
         "index_name": "my_index",
         "index_key": "your_64_character_hex_key_here",
         "items": [
           {
             "id": "item_1",
             "vector": [0.1, 0.2, 0.3, 0.4],
             "metadata": {"name": "Alice", "age": 30}
           },
           {
             "id": "item_2",
             "vector": [0.5, 0.6, 0.7, 0.8],
             "metadata": {"name": "Bob", "age": 40}
           },
           {
             "id": "item_3",
             "vector": [0.9, 0.10, 0.11, 0.12],
             "metadata": {"name": "Charlie", "age": 50}
           }
         ]
       }'
  ```
</CodeGroup>

For more info on metadata storage and filtering, see [Metadata Filtering](./metadata-filtering).

## Automatic Embedding Generation

<Tip>To use automatic embedding generation, use the [Docker Service](../intro/quickstart-docker) or install with `pip install cyborgdb-service[embeddings]`</Tip>

If you provided an `embedding_model` during index creation, you can automatically generate embeddings for items by providing `contents` to the `upsert()` call:

<CodeGroup>
  ```python Python SDK icon="python" theme={null}
  # ... index creation and embedding model setup
  embedding_model = "all-MiniLM-L6-v2"
  index = client.create_index(
    index_name="my_index",
    index_key=index_key,
    embedding_model=embedding_model
  )

  # Items to add to the encrypted index
  items = [
      {"id": "item_1", "contents": "Hello, World!"},
      {"id": "item_2", "contents": "Hello, Cyborg!"}
  ]

  # Add items to the encrypted index
  index.upsert(items)
  ```

  ```javascript JavaScript SDK icon="js" theme={null}
  // ... index creation and embedding model setup
  const embeddingModel = "all-MiniLM-L6-v2";
  const index = await client.createIndex({
      indexName: "my_index",
      indexKey,
      embeddingModel
  });

  // Items to add to the encrypted index
  const items = [
      {id: "item_1", contents: "Hello, World!"},
      {id: "item_2", contents: "Hello, Cyborg!"}
  ];

  // Add items to the encrypted index
  await index.upsert({ items });
  ```

  ```typescript TypeScript SDK icon="code" theme={null}
  import { VectorItem, UpsertRequest, EncryptedIndex, CreateIndexRequest } from 'cyborgdb';

  // ... index creation and embedding model setup
  const embeddingModel: string = "all-MiniLM-L6-v2";
  const indexParams: CreateIndexRequest = {
      indexName: "my_index",
      indexKey,
      embeddingModel
  };
  const index: EncryptedIndex = await client.createIndex(indexParams);

  // Items to add to the encrypted index
  const items: VectorItem[] = [
      {id: "item_1", contents: "Hello, World!"},
      {id: "item_2", contents: "Hello, Cyborg!"}
  ];

  // Add items to the encrypted index
  const params: UpsertRequest = { items };
  await index.upsert(params);
  ```

  ```go Go SDK icon="golang" theme={null}
  // Items to add to the encrypted index
  items := cyborgdb.VectorItems{
      {Id: "item_1", Contents: cyborgdb.NewNullableContents("Hello, World!")},
      {Id: "item_2", Contents: cyborgdb.NewNullableContents("Hello, Cyborg!")},
  }

  // Add items to the encrypted index
  err := index.Upsert(context.Background(), items)
  if err != nil {
      log.Fatal(err)
  }
  ```

  ```bash cURL icon="rectangle-terminal" theme={null}
  # For indexes created with embedding_model
  curl -X POST "http://localhost:8000/v1/vectors/upsert" \
       -H "X-API-Key: your-api-key" \
       -H "Content-Type: application/json" \
       -d '{
         "index_name": "my_index",
         "index_key": "your_64_character_hex_key_here",
         "items": [
           {
             "id": "item_1",
             "contents": "Hello, World!"
           },
           {
             "id": "item_2",
             "contents": "Hello, Cyborg!"
           }
         ]
       }'
  ```
</CodeGroup>

In this example, the `embedding_model` will automatically generate embeddings for the `contents` field. The contents will also be stored alongside the generated embeddings.

This feature uses various embedding models available through the service. You can use any model supported by the CyborgDB service, including models from the [HuggingFace Model Hub](https://huggingface.co/models).

## Automatic training on upsert

In v0.17, `upsert` may trigger background training automatically once the index has accumulated enough vectors (`num_vectors > n_lists * RETRAIN_THRESHOLD`, with `RETRAIN_THRESHOLD` defaulting to `10000`). When this happens, the upsert response carries two extra fields:

```json theme={null}
{
  "status": "success",
  "message": "Upserted 5000 vectors",
  "training_triggered": true,
  "training_message": "Index training has been triggered (vectors: 15000, threshold: 10000)"
}
```

Training runs asynchronously — the upsert itself does not block on it. Use `isTraining()` (per-index) or `GET /v1/indexes/training-status` (global) to poll progress.

To disable this behavior — e.g. when benchmarking a fixed index state — set `AUTO_TRAIN_DISABLED=true` on the service. Explicit `train()` / `POST /v1/indexes/train` keep working in either mode.

## API Reference

For more information on adding items to an encrypted index, refer to the API reference:

<CardGroup cols={2}>
  <Card title="REST API Reference" href="../../rest-api/encrypted-index/upsert" icon="rectangle-terminal">
    REST API reference for `/v1/vectors/upsert`
  </Card>

  <Card title="Python SDK Reference" href="../../python-sdk/encrypted-index/upsert" icon="python">
    API reference for `upsert()` in Python
  </Card>

  <Card title="JS/TS SDK Reference" href="../../js-ts-sdk/encrypted-index/upsert" icon="js">
    API reference for `upsert()` in JavaScript/TypeScript
  </Card>

  <Card title="Go SDK Reference" href="../../go-sdk/encrypted-index/upsert" icon="golang">
    API reference for `Upsert()` in Go
  </Card>
</CardGroup>