> ## 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 (Binary)

`upsert_binary()` sends vectors as base64-encoded little-endian `float32` instead of JSON arrays, which is faster for large batches. Unlike the two-argument form of [`upsert()`](./upsert), it also takes parallel `metadata` and `contents`.

```python theme={null}
index.upsert_binary(
    ids,
    vectors,
    metadata=None,
    contents=None,
)
```

### Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `ids` | `List[str]` | - | Unique identifier for each vector. Length must equal `vectors.shape[0]`. |
| `vectors` | `np.ndarray` (shape `(n, dim)`) | - | Vector data. Cast to little-endian `float32` if needed. |
| `metadata` | `List[Optional[Dict]]` | `None` | *(Optional)* Metadata per vector, same length as `ids`. Use `None` for entries without metadata. |
| `contents` | `List[Optional[str \| bytes]]` | `None` | *(Optional)* Contents per vector, same length as `ids`. Strings are stored as-is; bytes are base64-encoded first. Use `None` for entries without contents. |

<Warning>Don't upsert vectors containing `NaN` or infinite values. The service stores them, and later `get` or `query` calls on that index that return vectors or distances fail with a `5xx` error. The SDK doesn't check for them.</Warning>

### Returns

`None`

### Exceptions

<AccordionGroup>
  <Accordion title="cyborgdb.ValidationError">
    * Also a `TypeError`. `vectors` is not a NumPy array.
    * `vectors` is not 2-D, or `ids`, `metadata`, or `contents` differ in length from `vectors`. Raised before any request is sent.
    * The service rejects the batch (HTTP `400`), for example a vector with the wrong dimension.
  </Accordion>

  <Accordion title="cyborgdb.ServiceError / cyborgdb.TransportError">
    The service returns `5xx` or can't be reached.
  </Accordion>
</AccordionGroup>

See [Errors](../errors) for the full hierarchy.

### Example Usage

```python theme={null}
import numpy as np

ids = ["vec1", "vec2", "vec3"]
vectors = np.random.rand(3, 4).astype(np.float32)
metadata = [
    {"category": "news", "lang": "en"},
    {"category": "research"},
    None,
]
contents = ["First doc body", "Second doc body", None]

index.upsert_binary(ids, vectors, metadata=metadata, contents=contents)
print(index.get(["vec1"], include=["contents"]))
# Output: [{'id': 'vec1', 'contents': 'First doc body'}]
```

<Tip>For small batches, the item-dict form of [`upsert()`](./upsert) is easier to read. Use `upsert_binary()` when the vectors are already a NumPy array and JSON encoding time matters.</Tip>


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