Upsert (Binary)

upsert_binary is the low-level, high-throughput upsert path. Vectors are sent as base64-encoded binary instead of JSON arrays, which is significantly faster for large batches. Unlike the two-arg form of upsert(), this method also accepts parallel metadata and contents lists.

index.upsert_binary(
    ids,
    vectors,
    metadata=None,
    contents=None,
)

Parameters

Parameter	Type	Default	Description
`ids`	`List[str]`	-	Unique identifier for each vector. Length must match `vectors.shape[0]`.
`vectors`	`np.ndarray` (shape `(n, dim)`)	-	Vector data as a 2D numpy array. The SDK casts to little-endian `float32` if needed.
`metadata`	`List[Optional[Dict]]`	`None`	(Optional) Per-vector metadata. Same length as `ids`. Use `None` for entries without metadata.
`contents`	`List[Optional[str \| bytes]]`	`None`	(Optional) Per-vector contents. Same length as `ids`. Bytes are base64-encoded, strings are passed through; all contents are encrypted before storage. Use `None` for entries without contents.

Returns

None

Exceptions

Error

TypeError: vectors is not a numpy array.
ValueError: vectors.ndim != 2, or len(ids) != vectors.shape[0], or the server rejects the upsert.

Example Usage

import numpy as np

ids = ["vec1", "vec2", "vec3"]
vectors = np.random.rand(3, 384).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)

For small batches and most application code, prefer the dictionary form of upsert() for readability. Reach for upsert_binary when you have vectors already in numpy form and JSON encoding is on your critical path.

Introduction

Client

Encrypted Index

Types & Helpers

Parameters

Returns

Exceptions

Example Usage

​Parameters

​Returns

​Exceptions

​Example Usage

Parameters

Returns

Exceptions

Example Usage