docs/mintlify/cloud/search-api/migration.mdx
import { Callout } from '/snippets/callout.mdx';
<Callout> The `query()` and `get()` methods will continue to be supported, so migration to the Search API is optional. </Callout>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 |
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 |
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 |
from chromadb import Search
results = collection.search( Search( rank={"$knn": {"query": "machine learning"}}, limit=10 ) )
```typescript TypeScript
// Legacy API
const results = await collection.query({
queryEmbeddings: [[0.1, 0.2, 0.3]],
nResults: 10
});
// Search API - with text query
import { Search } from 'chromadb';
const results2 = await collection.search(
new Search({
rank: { $knn: { query: "machine learning" } },
limit: 10
})
);
use chroma::types::{QueryVector, RankExpr, SearchPayload};
let results = collection
.query(vec![vec![0.1, 0.2, 0.3]], Some(10), None, None, None)
.await?;
let results2 = collection
.search(vec![SearchPayload::default()
.rank(RankExpr::Knn {
query: QueryVector::Dense(vec![0.1, 0.2, 0.3]),
key: chroma::types::Key::Embedding,
limit: 10,
default: None,
return_rank: false,
})
.limit(Some(10), 0)])
.await?;
results = collection.search( Search( rank={"$knn": {"query": "quantum computing"}}, where={"#document": {"$contains": "quantum"}}, limit=5 ) )
```typescript TypeScript
// Legacy API
const results = await collection.query({
queryEmbeddings: [[0.1, 0.2, 0.3]],
nResults: 5,
whereDocument: { $contains: "quantum" }
});
// Search API
const results2 = await collection.search(
new Search({
rank: { $knn: { query: "quantum computing" } },
where: { "#document": { $contains: "quantum" } },
limit: 5
})
);
results = collection.search( Search( where={"$and": [ {"category": "science"}, {"#document": {"$contains": "quantum"}} ]}, rank={"$knn": {"query": "quantum physics"}}, limit=10 ) )
```typescript TypeScript
// Legacy API
const results = await collection.query({
queryEmbeddings: [[0.1, 0.2, 0.3]],
nResults: 10,
where: { category: "science" },
whereDocument: { $contains: "quantum" }
});
// Search API - combine filters with $and
const results2 = await collection.search(
new Search({
where: {
$and: [
{ category: "science" },
{ "#document": { $contains: "quantum" } }
]
},
rank: { $knn: { query: "quantum physics" } },
limit: 10
})
);
results = collection.search( Search( where={"#id": {"$in": ["id1", "id2", "id3"]}} ) )
```typescript TypeScript
// Legacy API
const results = await collection.get({
ids: ["id1", "id2", "id3"]
});
// Search API
const results2 = await collection.search(
new Search({
where: { "#id": { $in: ["id1", "id2", "id3"] } }
})
);
results = collection.search( Search( where={"status": "active"}, limit={"limit": 100, "offset": 50} ) )
```typescript TypeScript
// Legacy API
const results = await collection.get({
where: { status: "active" },
limit: 100,
offset: 50
});
// Search API
const results2 = await collection.search(
new Search({
where: { status: "active" },
limit: { limit: 100, offset: 50 }
})
);
The Search API supports text queries directly - they are automatically converted to embeddings using the collection's configured embedding function.
<CodeGroup> ```python Python # Legacy API collection.query(query_texts=["search text"])collection.search(Search(rank={"$knn": {"query": "search text"}}))
```typescript TypeScript
// Legacy API
await collection.query({ queryTexts: ["search text"] });
// Search API - direct text query
await collection.search(
new Search({ rank: { $knn: { query: "search text" } } })
);
The Search API allows different parameters for each search in a batch:
<CodeGroup> ```python Python # Legacy - same parameters for all queries results = collection.query( query_embeddings=[emb1, emb2, emb3], n_results=10, where={"category": "science"} # Same filter for all )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)
```typescript TypeScript
// Legacy - same parameters for all queries
const results = await collection.query({
queryEmbeddings: [emb1, emb2, emb3],
nResults: 10,
where: { category: "science" } // Same filter for all
});
// Search API - different parameters per search
const searches = [
new Search({ rank: { $knn: { query: "machine learning" } }, limit: 10, where: { category: "science" } }),
new Search({ rank: { $knn: { query: "neural networks" } }, limit: 5, where: { category: "tech" } }),
new Search({ rank: { $knn: { query: "artificial intelligence" } }, limit: 20 }) // No filter
];
const results2 = await collection.search(searches);