Skip to main content
The query() and get() methods will continue to be supported, so migration to the Search API is optional.

​
Parameter Mapping

The Search API is available in Chroma Cloud. This guide uses dictionary syntax for minimal migration effort.

​
query() Parameters

Legacy query()Search APINotes
query_embeddingsrank={"$knn": {"query": ...}}Can use text or embeddings
query_textsrank={"$knn": {"query": "text"}}Text queries now supported
query_imagesNot yet supportedImage queries coming in future release
query_urisNot yet supportedURI queries coming in future release
n_resultslimitDirect mapping
idswhere={"#id": {"$in": [...]}}Filter by IDs
wherewhereSame syntax
where_documentwhere={"#document": {...}}Use #document field
includeselectSee field mapping below

​
get() Parameters

Legacy get()Search APINotes
idswhere={"#id": {"$in": [...]}}Filter by IDs
wherewhereSame syntax
where_documentwhere={"#document": {...}}Use #document field
limitlimitDirect mapping
offsetlimit={"offset": ...}Part of limit dict
includeselectSee field mapping below

​
Include/Select Field Mapping

Legacy includeSearch API selectDescription
"ids"Always includedIDs are always returned
"documents""#document"Document content
"metadatas""#metadata"All metadata fields
"embeddings""#embedding"Vector embeddings
"distances""#score"Distance/score from query
"uris""#uri"Document URIs

​
Examples

# Legacy API
results = collection.query(
    query_embeddings=[[0.1, 0.2, 0.3]],
    n_results=10
)

# Search API - with text query
from chromadb import Search

results = collection.search(
    Search(
        rank={"$knn": {"query": "machine learning"}},
        limit=10
    )
)

​
Document Filtering

# Legacy API
results = collection.query(
    query_embeddings=[[0.1, 0.2, 0.3]],
    n_results=5,
    where_document={"$contains": "quantum"}
)

# Search API
results = collection.search(
    Search(
        rank={"$knn": {"query": "quantum computing"}},
        where={"#document": {"$contains": "quantum"}},
        limit=5
    )
)

​
Combined Filters

# Legacy API
results = collection.query(
    query_embeddings=[[0.1, 0.2, 0.3]],
    n_results=10,
    where={"category": "science"},
    where_document={"$contains": "quantum"}
)

# Search API - combine filters with $and
results = collection.search(
    Search(
        where={"$and": [
            {"category": "science"},
            {"#document": {"$contains": "quantum"}}
        ]},
        rank={"$knn": {"query": "quantum physics"}},
        limit=10
    )
)

​
Get by IDs

# Legacy API
results = collection.get(
    ids=["id1", "id2", "id3"]
)

# Search API
results = collection.search(
    Search(
        where={"#id": {"$in": ["id1", "id2", "id3"]}}
    )
)

​
Pagination

# Legacy API
results = collection.get(
    where={"status": "active"},
    limit=100,
    offset=50
)

# Search API
results = collection.search(
    Search(
        where={"status": "active"},
        limit={"limit": 100, "offset": 50}
    )
)

​
Key Differences

​
Text Queries Now Supported

The Search API supports text queries directly - they are automatically converted to embeddings using the collection’s configured embedding function. 
# Legacy API
collection.query(query_texts=["search text"])

# Search API - direct text query
collection.search(Search(rank={"$knn": {"query": "search text"}}))

​
New Capabilities

  • Advanced filtering - Complex logical expressions
  • Custom ranking - Combine and transform ranking expressions
  • Hybrid search - RRF for combining multiple strategies
  • Selective fields - Return only needed fields
  • Flexible batch operations - Different parameters per search in batch

​
Flexible Batch Operations

The Search API allows different parameters for each search in a batch: 
# Legacy - same parameters for all queries
results = collection.query(
    query_embeddings=[emb1, emb2, emb3],
    n_results=10,
    where={"category": "science"}  # Same filter for all
)

# Search API - different parameters per search
searches = [
    Search(rank={"$knn": {"query": "machine learning"}}, limit=10, where={"category": "science"}),
    Search(rank={"$knn": {"query": "neural networks"}}, limit=5, where={"category": "tech"}),
    Search(rank={"$knn": {"query": "artificial intelligence"}}, limit=20)  # No filter
]
results = collection.search(searches)

​
Migration Tips

  • Start with simple queries before complex ones
  • Test both APIs in parallel during migration
  • Use batch operations to reduce API calls
  • Text queries are now supported - use them directly in the Search API

​
Next Steps