Search ↗

chroma reference intermediate ide search
no
Summary: Reference guide for Search dictionary syntax used in Chroma.

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.

Reference guide for Search dictionary syntax used in Chroma.

Search dictionaries define filtering, ranking, grouping, pagination, and field selection for Chroma queries. Each SDK provides a DSL, but they compile to the same JSON format that you can construct directly.

For example, SDK code like this:

from chromadb import Search, K, Knn, GroupBy, MinK

search = Search(
    where=K("status") == "active",
    rank=Knn(query="machine learning research", limit=100),
    group_by=GroupBy(keys=K("category"), aggregate=MinK(keys=K.SCORE, k=2)),
    limit=10,
    select=[K.DOCUMENT, K.SCORE, "category"]
)
import { Search, K, Knn, GroupBy, MinK } from 'chromadb';

const search = new Search({
  where: K("status").eq("active"),
  rank: Knn({ query: "machine learning research", limit: 100 }),
  groupBy: new GroupBy([K("category")], new MinK([K.SCORE], 2)),
  limit: 10,
  select: [K.DOCUMENT, K.SCORE, "category"]
});
use chroma::types::{Aggregate, GroupBy, Key, QueryVector, RankExpr, SearchPayload};

let search = SearchPayload::default()
    .r#where(Key::field("status").eq("active"))
    .rank(RankExpr::Knn {
        query: QueryVector::Dense(vec![0.1, 0.2, 0.3]),
        key: Key::Embedding,
        limit: 100,
        default: None,
        return_rank: false,
    })
    .group_by(GroupBy {
        keys: vec![Key::field("category")],
        aggregate: Some(Aggregate::MinK {
            keys: vec![Key::Score],
            k: 2,
        }),
    })
    .limit(Some(10), 0)
    .select([Key::Document, Key::Score, Key::field("category")]);

Gets compiled to this JSON:

{
  "where": {"status": {"$eq": "active"}},
  "rank": {"$knn": {"query": "machine learning research", "limit": 100}},
  "group_by": {
    "keys": ["category"],
    "aggregate": {"$min_k": {"keys": ["#score"], "k": 2}}
  },
  "limit": {"limit": 10, "offset": 0},
  "select": {"keys": ["#document", "#score", "category"]}
}

This reference describes the Search dictionary format and rules. For related dictionary references, see Where Filters.

JSON Format#

Basic Structure#

A Search dictionary is an object with optional keys:

{
  "where": { /* where filter dictionary */ },
  "rank": { /* rank expression dictionary */ },
  "group_by": { /* group by dictionary */ },
  "limit": {"limit": 10, "offset": 0},
  "select": {"keys": ["#document", "#score"]}
}

All keys are optional. Omitted keys use Search defaults.

Component Schemas#

where#

where uses the Where Filter dictionary schema.

{
  "where": ...
}

See Where Filters for full operator and rule definitions.

rank#

rank must be a dictionary with exactly one top-level operator.

{
  "rank": RankExpr
}
{
  "RankExpr": {"$val": "number"}
}
{
  "RankExpr": {
    "$knn": {
      "query": "string | number[] | SparseVector",
      "key": "string (optional)",
      "limit": "positive integer (optional)",
      "default": "number (optional)",
      "return_rank": "boolean (optional)"
    }
  }
}
{
  "RankExpr": {
    "$op": ...
  }
}
OperatorFormat
$sum["RankExpr", "RankExpr", "... (min 2)"]
$mul["RankExpr", "RankExpr", "... (min 2)"]
$max["RankExpr", "RankExpr", "... (min 2)"]
$min["RankExpr", "RankExpr", "... (min 2)"]
$sub (l-r){ "left": "RankExpr", "right": "RankExpr" }
$div (l/r){ "left": "RankExpr", "right": "RankExpr" }
$abs"RankExpr"
$exp (ex)"RankExpr"
$log (Natural logarithm)"RankExpr"

group_by#

group_by can be omitted or provided as a dictionary with both keys and aggregate.

{
  "group_by": {
    "keys": ["metadata_field", "... (min 1)"],
    "aggregate": {
      "$min_k": { // Or $max_k
        "keys": ["metadata_field_or_#score", "... (min 1)"],
        "k": "positive integer"
      }
    }
  }
}

limit#

Controls pagination.

{
  "limit": {
    "limit": 10, (optional, default 0)
    "offset": 20 (optional)
  }
}

select#

Controls returned fields. Use built-ins (#id, #document, #embedding, #metadata, #score) and/or metadata field names.

{
  "select": {
    "keys": ["#id", "#document", "#metadata", "#score", "author"]
  }
}

Built with Mintlify.

Link last verified June 7, 2026. View original ↗
Source: Chroma Docs
Link last verified: 2026-04-05