Skip to main content

​
Collection Methods

​
count

Return the number of records in the collection.

​
add

Add records to the collection.
​
ids
Union[str, IDs]
required
Record IDs to add.
​
embeddings
Optional[Embeddings]
Embeddings to add. If None, embeddings are computed.
​
metadatas
Union[Optional[Metadatas], List[Optional[Metadatas]], None]
Optional metadata for each record.
​
documents
Union[str, IDs, None]
Optional documents for each record.
​
images
Optional[Embeddings]
Optional images for each record.
​
uris
Union[str, IDs, None]
Optional URIs for loading images.
Raises:
  • ValueError: If embeddings and documents are both missing.
  • ValueError: If embeddings and documents are both provided.
  • ValueError: If lengths of provided fields do not match.
  • ValueError: If an ID already exists.

​
get

Retrieve records from the collection. If no filters are provided, returns records up to limit starting at offset.
​
ids
Union[str, IDs, None]
If provided, only return records with these IDs.
​
where
Optional[Dict[Union[str, Literal[$and], Literal[$or]], Where]]
A Where filter used to filter based on metadata values.
​
limit
Optional[int]
Maximum number of results to return.
​
offset
Optional[int]
Number of results to skip before returning.
​
where_document
Optional[Dict[Where, Union[str, List[Dict[Where, Union[str, List[WhereDocument]]]]]]]
A WhereDocument filter used to filter based on K.DOCUMENT.
​
include
List[Literal[documents, embeddings, metadatas, distances, uris, data]]
Fields to include in results. Can contain “embeddings”, “metadatas”, “documents”, “uris”. Defaults to “metadatas” and “documents”.
Returns: Retrieved records and requested fields as a GetResult object.

​
peek

Return the first limit records from the collection.
​
limit
int
Maximum number of records to return.
Returns: Retrieved records and requested fields.

​
query

Query for the K nearest neighbor records in the collection. This is a batch query API. Multiple queries can be performed at once by providing multiple embeddings, texts, or images. 
query_1 = [0.1, 0.2, 0.3]
query_2 = [0.4, 0.5, 0.6]
results = collection.query(
    query_embeddings=[query_1, query_2],
    n_results=10,
)
If query_texts, query_images, or query_uris are provided, the collection’s embedding function will be used to create embeddings before querying the API. The ids, where, where_document, and include parameters are applied to all queries.
​
query_embeddings
Optional[Embeddings]
Raw embeddings to query for.
​
query_texts
Union[str, IDs, None]
Documents to embed and query against.
​
query_images
Optional[Embeddings]
Images to embed and query against.
​
query_uris
Union[str, IDs, None]
URIs to be loaded and embedded.
​
ids
Union[str, IDs, None]
Optional subset of IDs to search within.
​
n_results
int
Number of neighbors to return per query.
​
where
Optional[Dict[Union[str, Literal[$and], Literal[$or]], Where]]
Metadata filter.
​
where_document
Optional[Dict[Where, Union[str, List[Dict[Where, Union[str, List[WhereDocument]]]]]]]
Document content filter.
​
include
List[Literal[documents, embeddings, metadatas, distances, uris, data]]
Fields to include in results. Can contain “embeddings”, “metadatas”, “documents”, “uris”, “distances”. Defaults to “metadatas”, “documents”, “distances”.
Returns: Nearest neighbor results. Raises:
  • ValueError: If no query input is provided.
  • ValueError: If multiple query input types are provided.

​
modify

Update collection name, metadata, or configuration.
​
name
Optional[str]
New collection name.
​
metadata
Optional[Dict[str, Any]]
New metadata for the collection.
​
configuration
Optional[UpdateCollectionConfiguration]
New configuration for the collection.

​
update

Update existing records by ID. Records are provided in columnar format. If provided, the embeddings, metadatas, documents, and uris lists must be the same length. Entries in each list correspond to the same record. 
ids = ["id1", "id2", "id3"]
embeddings = [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6], [0.7, 0.8, 0.9]]
metadatas = [{"key": "value"}, {"key": "value"}, {"key": "value"}]
documents = ["document1", "document2", "document3"]
uris = ["uri1", "uri2", "uri3"]
collection.update(ids, embeddings, metadatas, documents, uris)
If embeddings are not provided, the embeddings will be computed based on documents using the collection’s embedding function.
​
ids
Union[str, IDs]
required
Record IDs to update.
​
embeddings
Optional[Embeddings]
Updated embeddings. If None, embeddings are computed.
​
metadatas
Union[Optional[Metadatas], List[Optional[Metadatas]], None]
Updated metadata.
​
documents
Union[str, IDs, None]
Updated documents.
​
images
Optional[Embeddings]
Updated images.
​
uris
Union[str, IDs, None]
Updated URIs for loading images.

​
upsert

Create or update records by ID.
​
ids
Union[str, IDs]
required
Record IDs to upsert.
​
embeddings
Optional[Embeddings]
Embeddings to add or update. If None, embeddings are computed.
​
metadatas
Union[Optional[Metadatas], List[Optional[Metadatas]], None]
Metadata to add or update.
​
documents
Union[str, IDs, None]
Documents to add or update.
​
images
Optional[Embeddings]
Images to add or update.
​
uris
Union[str, IDs, None]
URIs for loading images.

​
delete

Delete records by ID or filters. All documents that match the ids or where and where_document filters will be deleted.
​
ids
Optional[IDs]
Record IDs to delete.
​
where
Optional[Dict[Union[str, Literal[$and], Literal[$or]], Where]]
Metadata filter.
​
where_document
Optional[Dict[Where, Union[str, List[Dict[Where, Union[str, List[WhereDocument]]]]]]]
Document content filter.
Raises:
  • ValueError: If no IDs or filters are provided.

​
Types

​
GetResult

Result payload for collection.get() operations. The returned records are in columnar form. Corresponding entries in each list correspond to the same record. 
results = collection.get(ids=["id1", "id2", "id3"])
records = zip(results["ids"], results["documents"], results["metadatas"])
for id, document, metadata in records:
    print(id, document, metadata)
GetResult will only include ids and the fields specified in the include param when making the get() operation. Properties
​
ids
IDs
​
embeddings
Optional[Embeddings]
​
documents
Optional[IDs]
​
uris
Optional[IDs]
​
data
Optional[Optional[Embeddings]]
​
metadatas
Optional[List[Optional[Metadatas]]]
​
included
List[Literal[documents, embeddings, metadatas, distances, uris, data]]

​
QueryResult

Result payload for collection.query() operations. The returned records are batches of records in columnar form. 
results = collection.query(query_embeddings=[batch_1, batch_2, ...])
batches = zip(results["ids"], results["documents"], results["metadatas"])
Each batch is a list of records in columnar form. 
for batch in batches:
    records = zip(batch["ids"], batch["documents"], batch["metadatas"])
    for id, document, metadata in records:
        print(id, document, metadata)
QueryResult will only include ids and the fields specified in the include param when making the query() operation. Properties
​
ids
List[IDs]
​
embeddings
Optional[Embeddings]
​
documents
Optional[List[IDs]]
​
uris
Optional[List[IDs]]
​
data
Optional[List[Optional[Embeddings]]]
​
metadatas
Optional[List[List[Optional[Metadatas]]]]
​
distances
Optional[List[List[float]]]
​
included
List[Literal[documents, embeddings, metadatas, distances, uris, data]]