> ## 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.

# Upsert

Adds or updates vector embeddings in the index. If an item already exists at `id`, then it will be overwritten.

```cpp theme={null}
void Upsert(const std::vector<cyborg::ItemID>& ids,
            Array2D<float>& vectors,
            const std::vector<std::vector<uint8_t>>& contents = {},
            const std::vector<std::string>& json_metadata_array = {});
```

### Parameters

| Parameter             | Type                                 | Description                                            |
| --------------------- | ------------------------------------ | ------------------------------------------------------ |
| `ids`                 | `std::vector<cyborg::ItemID>&`       | Unique identifiers for each vector.                    |
| `vectors`             | [`Array2D<float>`](../types#array2d) | 2D container with vector embeddings to index.          |
| `contents`            | `std::vector<std::vector<uint8_t>>&` | *(Optional)* Item contents in bytes.                   |
| `json_metadata_array` | `std::vector<std::string>&`          | *(Optional)* Item metadata in serialized JSON strings. |

<Tip>For more info on metadata, see [Metadata Filtering](../../guides/data-operations/metadata-filtering).</Tip>

### Exceptions

<AccordionGroup>
  <Accordion title="std::invalid_argument">
    * Throws if vector dimensions are incompatible with the index configuration.
    * Throws if index was not created or loaded yet.
    * Throws if there is a mismatch between the number of `vectors`, `ids`, `contents` or `metadata`.
  </Accordion>

  <Accordion title="std::runtime_error">
    * Throws if the vectors could not be upserted.
  </Accordion>
</AccordionGroup>

### Example Usage

```cpp theme={null}
cyborg::Array2D<float> embeddings{{0.1, 0.2, 0.3}, {0.4, 0.5, 0.6}};
std::vector<std::string> ids = {"item_1", "item_2"};

// Upsert without additional item data
index->Upsert(ids, embeddings);

// Upsert with associated items
std::vector<std::vector<uint8_t>> items = {
    {'a', 'b', 'c'}, {'d', 'e', 'f'}
};
index->Upsert(ids, embeddings, items);

// Upsert with metadata
std::vector<std::string> metadata = {"{\"type\": \"image\"}", "{\"type\": \"text\"}"};
index->Upsert(ids, embeddings, items, metadata);
```