Adds or updates vector embeddings in the index. Accepts a list of dictionaries, where each dictionary represents a vector with its ID. 
def upsert(self, items: List[Dict[str, Any]])

​
Parameters

ParameterTypeDescription
itemsList[Dict[str, Any]]A list of dictionaries, where each dictionary has the format {"id": str, "vector": List[float], "contents": Union[bytes, str], "metadata": Dict[str, str]}.
Where each item dictionary has the following fields:
ParameterTypeDescription
idstrUnique string identifier for the item.
vectorList[float]Embedding vector as a list of floats (optional if index is configured to compute embeddings).
contentsbytes, str or ImageItem contents (optional). Must be a str or Image if index is configured to compute embeddings.
metadataDict[str, any]Dictionary of key-value metadata pairs associated with the vector (optional).
If embedding auto-generation is enabled (by setting the embedding_model parameter in create_index()), then the vector parameter is optional. If vector provided, then it will be used (its dimensionality must match that of the embedding_model). If vector is not provided, a vector embedding will be auto-generated from contents using sentence-transformers. contents must be text in this case.
For more info on metadata, see Metadata Filtering.

​
Exceptions

​
Example Usage

# Initial configuration already done...

# Load Index
index = client.load_index(index_name=index_name, index_key=index_key)

# Single upsert (wrapped in a list)
index.upsert([{"id": "item_1", "vector": [0.1, 0.2, 0.3]}])

# Upsert with metadata
index.upsert([
  {"id": "item_1",
   "vector": [0.1, 0.2, 0.3],
   "metadata": {"type": "dog", "temperament": "good boy"}
  }
])

# Batch upsert
index.upsert([
    {"id": "item_1", "vector": [0.1, 0.2, 0.3]},
    {"id": "item_2", "vector": [0.4, 0.5, 0.6]}
])

# Upsert with items
index.upsert([
    {"id": "item_1", "vector": [0.1, 0.1, 0.1, 0.1], "contents": b'item_contents_here...'}, # Bytes
    {"id": "item_2", "vector": [0.2, 0.2, 0.2, 0.2], "contents": "item_contents_here..."} # Text
])
You can pass the id and vector fields as tuples, if you wish to skip the dictionary. On big datasets, this can make a signficant difference in memory usage.

​
Upsert Secondary Overload: NumPy Array Format

This format is optimal for large batches due to its memory efficiency and compatibility with batch processing optimizations. It is primarily intended for benchmarking purposes (hence the use of int for IDs).
def upsert(self, ids: np.ndarray, vectors: np.ndarray)
Accepts two NumPy arrays:
  • A 1D array of identifiers (strings or integers) for the unique IDs.
  • A 2D array of float32 values for the vector embeddings.
This structure is suited for efficient handling of large batches, with type safety for IDs and embeddings.

​
Parameters

ParameterTypeDescription
idsnp.ndarray1D NumPy array of shape (num_items,) containing unique identifiers for each vector. Can be string or integer dtype. Length must match vectors.
vectorsnp.ndarray2D NumPy array of shape (num_items, vector_dim) with dtype=float32, representing vector embeddings.

​
Exceptions

​
Example Usage

import numpy as np

# Load index
index = client.load_index(index_name=index_name, index_key=index_key)

# NumPy-based upsert with two arrays
vectors = np.array([[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]], dtype=np.float32)  # 2 vectors of dimension 3
ids = np.array(["item_101", "item_102"])  # Unique string IDs for each vector

index.upsert(ids, vectors)