Migration Guide ↗

Summary: Migrate from legacy 'query()' and 'get()' to the Search API.

Original Documentation

Documentation Index#
Fetch the complete documentation index at: https://docs.trychroma.com/llms.txt Use this file to discover all available pages before exploring further.

Migrate from legacy query() and get() to the Search API.

export const Callout = ({title, children}) =>

{title && <p className="block mb-2"><strong>{title}</strong></p>}
{children}

;

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
    )
)

// 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?;

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
    )
)

// 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
  })
);

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
    )
)

// 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
  })
);

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
const results = await collection.get({
  ids: ["id1", "id2", "id3"]
});

// Search API
const results2 = await collection.search(
  new 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}
    )
)

// 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 }
  })
);

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"}}))

// Legacy API
await collection.query({ queryTexts: ["search text"] });

// Search API - direct text query
await collection.search(
  new 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)

// 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);

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#

Search Basics - Core search concepts
Filtering - Advanced filtering options
Examples - Practical search patterns

Link last verified June 7, 2026. View original ↗

Source: Chroma Docs

Link last verified: 2026-03-04