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(), it also takes parallel metadata and contents.

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.

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.

Returns

None

Exceptions

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.

cyborgdb.ServiceError / cyborgdb.TransportError

The service returns 5xx or can’t be reached.

See Errors for the full hierarchy.

Example Usage

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'}]

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

Introduction

Client

Encrypted Index

Types & Helpers

Parameters

Returns

Exceptions

Example Usage

​Parameters

​Returns

​Exceptions

​Example Usage

Parameters

Returns

Exceptions

Example Usage