Migration Guide
Migrate from the legacy query() and get() methods to the new Search API.
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 API | Notes |
|---|
query_embeddings | rank={"$knn": {"query": ...}} | Can use text or embeddings |
query_texts | rank={"$knn": {"query": "text"}} | Text queries now supported |
query_images | Not yet supported | Image queries coming in future release |
query_uris | Not yet supported | URI queries coming in future release |
n_results | limit | Direct mapping |
ids | where={"#id": {"$in": [...]}} | Filter by IDs |
where | where | Same syntax |
where_document | where={"#document": {...}} | Use #document field |
include | select | See field mapping below |
get() Parameters
Legacy get() | Search API | Notes |
|---|
ids | where={"#id": {"$in": [...]}} | Filter by IDs |
where | where | Same syntax |
where_document | where={"#document": {...}} | Use #document field |
limit | limit | Direct mapping |
offset | limit={"offset": ...} | Part of limit dict |
include | select | See field mapping below |
Include/Select Field Mapping
Legacy include | Search API select | Description |
|---|
"ids" | Always included | IDs 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
Basic Similarity Search
# 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"]}}
)
)
# 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
