Group By & Aggregation ↗

chroma guide intermediate search

Summary: Learn how to group search results by metadata keys and select the top results from each group. GroupBy is useful for diversifying results, deduplication, and category-aware ranking.

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.

Learn how to group search results by metadata keys and select the top results from each group. GroupBy is useful for diversifying results, deduplication, and category-aware ranking.

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

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

;

GroupBy currently requires a ranking expression to be specified. Support for grouping without ranking is planned for a future release.

How Grouping Works#

GroupBy organizes ranked results into groups based on metadata keys, then performs aggregation on each group. Currently, aggregation supports MinK and MaxK, which select the top k results from each group based on the specified sorting keys.

After grouping and aggregation, results from all groups are flattened and sorted by score. The limit() method operates on this flattened list.

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

# Get top 3 results per category, ordered by score
search = (Search()
    .rank(Knn(query="machine learning research"))
    .group_by(GroupBy(
        keys=K("category"),
        aggregate=MinK(keys=K.SCORE, k=3)
    ))
    .limit(30)
    .select(K.DOCUMENT, K.SCORE, "category"))

results = collection.search(search)

import { Search, K, Knn, GroupBy, MinK } from 'chromadb';

// Get top 3 results per category, ordered by score
const search = new Search()
  .rank(Knn({ query: "machine learning research" }))
  .groupBy(new GroupBy(
    [K("category")],
    new MinK([K.SCORE], 3)
  ))
  .limit(30)
  .select(K.DOCUMENT, K.SCORE, "category");

const results = await collection.search(search);

use chroma::types::{Aggregate, GroupBy, Key, QueryVector, RankExpr, SearchPayload};

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

let results = collection.search(vec![search]).await?;

The GroupBy Class#

The GroupBy class specifies how to partition results and which records to keep from each partition.

from chromadb import GroupBy, MinK, K

# Single grouping key
GroupBy(
    keys=K("category"),
    aggregate=MinK(keys=K.SCORE, k=3)
)

# Multiple grouping keys
GroupBy(
    keys=[K("category"), K("year")],
    aggregate=MinK(keys=K.SCORE, k=1)
)

import { GroupBy, MinK, K } from 'chromadb';

// Single grouping key
new GroupBy(
  [K("category")],
  new MinK([K.SCORE], 3)
);

// Multiple grouping keys
new GroupBy(
  [K("category"), K("year")],
  new MinK([K.SCORE], 1)
);

GroupBy Parameters#

Parameter	Type	Description
`keys`	Key or List[Key]	Metadata key(s) to group by
`aggregate`	MinK or MaxK	Aggregation function to select top k records within each group

Aggregation Functions#

MinK#

Keeps the k records with the smallest values for the specified keys. Use MinK when lower values are better (e.g., distance scores, prices, priorities).

from chromadb import MinK, K

# Keep 3 records with lowest scores per group
MinK(keys=K.SCORE, k=3)

# Keep 2 records with lowest priority, then lowest score as tiebreaker
MinK(keys=[K("priority"), K.SCORE], k=2)

import { MinK, K } from 'chromadb';

// Keep 3 records with lowest scores per group
new MinK([K.SCORE], 3);

// Keep 2 records with lowest priority, then lowest score as tiebreaker
new MinK([K("priority"), K.SCORE], 2);

Parameter	Type	Description
`keys`	Key or List[Key]	Key(s) to sort by in ascending order
`k`	int	Number of records to keep from each group

MaxK#

Keeps the k records with the largest values for the specified keys. Use MaxK when higher values are better (e.g., ratings, relevance scores, dates).

from chromadb import MaxK, K

# Keep 3 records with highest ratings per group
MaxK(keys=K("rating"), k=3)

# Keep 2 records with highest year, then highest rating as tiebreaker
MaxK(keys=[K("year"), K("rating")], k=2)

import { MaxK, K } from 'chromadb';

// Keep 3 records with highest ratings per group
new MaxK([K("rating")], 3);

// Keep 2 records with highest year, then highest rating as tiebreaker
new MaxK([K("year"), K("rating")], 2);

Parameter	Type	Description
`keys`	Key or List[Key]	Key(s) to sort by in descending order
`k`	int	Number of records to keep from each group

Key References#

Use K.SCORE to reference the search score, or K("field_name") for metadata fields.

from chromadb import K

# Built-in score key
K.SCORE  # References "#score" - the search/ranking score

# Metadata field keys
K("category")   # References the "category" metadata field
K("priority")   # References the "priority" metadata field
K("year")       # References the "year" metadata field

import { K } from 'chromadb';

// Built-in score key
K.SCORE;  // References "#score" - the search/ranking score

// Metadata field keys
K("category");   // References the "category" metadata field
K("priority");   // References the "priority" metadata field
K("year");       // References the "year" metadata field

Common Patterns#

Single Key Grouping#

Group by one metadata field and keep the top results from each group.

# Top 2 articles per category by relevance
search = (Search()
    .rank(Knn(query="climate change impacts"))
    .group_by(GroupBy(
        keys=K("category"),
        aggregate=MinK(keys=K.SCORE, k=2)
    ))
    .limit(20))

// Top 2 articles per category by relevance
const search = new Search()
  .rank(Knn({ query: "climate change impacts" }))
  .groupBy(new GroupBy(
    [K("category")],
    new MinK([K.SCORE], 2)
  ))
  .limit(20);

Multiple Key Grouping#

Group by combinations of metadata fields for finer-grained control.

# Top 1 article per (category, year) combination
search = (Search()
    .rank(Knn(query="renewable energy"))
    .group_by(GroupBy(
        keys=[K("category"), K("year")],
        aggregate=MinK(keys=K.SCORE, k=1)
    ))
    .limit(30))

// Top 1 article per (category, year) combination
const search = new Search()
  .rank(Knn({ query: "renewable energy" }))
  .groupBy(new GroupBy(
    [K("category"), K("year")],
    new MinK([K.SCORE], 1)
  ))
  .limit(30);

Multiple Ranking Keys with Tiebreakers#

Sort within groups by multiple criteria when the primary key has ties.

# Top 2 per category: sort by priority first, then by score
search = (Search()
    .rank(Knn(query="artificial intelligence"))
    .group_by(GroupBy(
        keys=K("category"),
        aggregate=MinK(keys=[K("priority"), K.SCORE], k=2)
    ))
    .limit(20))

// Top 2 per category: sort by priority first, then by score
const search = new Search()
  .rank(Knn({ query: "artificial intelligence" }))
  .groupBy(new GroupBy(
    [K("category")],
    new MinK([K("priority"), K.SCORE], 2)
  ))
  .limit(20);

Dictionary Syntax#

You can also construct GroupBy using dictionary syntax for programmatic query building.

# GroupBy with MinK
search = Search(
    rank={"$knn": {"query": "machine learning", "limit": 100}},
    group_by={
        "keys": ["category"],
        "aggregate": {"$min_k": {"keys": ["#score"], "k": 3}}
    },
    limit=30
)

# GroupBy with MaxK
search = Search(
    rank={"$knn": {"query": "top rated products", "limit": 100}},
    group_by={
        "keys": ["category", "brand"],
        "aggregate": {"$max_k": {"keys": ["rating", "#score"], "k": 2}}
    },
    limit=20
)

// GroupBy with MinK
const search1 = new Search({
  rank: { $knn: { query: "machine learning", limit: 100 } },
  groupBy: {
    keys: ["category"],
    aggregate: { $min_k: { keys: ["#score"], k: 3 } }
  },
  limit: 30
});

// GroupBy with MaxK
const search2 = new Search({
  rank: { $knn: { query: "top rated products", limit: 100 } },
  groupBy: {
    keys: ["category", "brand"],
    aggregate: { $max_k: { keys: ["rating", "#score"], k: 2 } }
  },
  limit: 20
});

Edge Cases and Important Behavior#

Groups with Fewer Records#

If a group has fewer records than the requested k, all records from that group are returned.

# Request top 5 per category, but "rare_category" only has 2 documents
# Result: "rare_category" returns 2, other categories return up to 5
search = (Search()
    .rank(Knn(query="search query"))
    .group_by(GroupBy(keys=K("category"), aggregate=MinK(keys=K.SCORE, k=5)))
    .limit(50))

// Request top 5 per category, but "rare_category" only has 2 documents
// Result: "rare_category" returns 2, other categories return up to 5
const search = new Search()
  .rank(Knn({ query: "search query" }))
  .groupBy(new GroupBy([K("category")], new MinK([K.SCORE], 5)))
  .limit(50);

Missing Metadata Keys#

Documents missing the grouping key are treated as having a null/None value for that key, and are grouped together.

Limit Still Applies#

The Search.limit() still controls the final number of results returned after grouping. Set it high enough to include results from all groups.

Complete Example#

Here’s a practical example showing diversified search results across categories:

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

# Diversified product search - ensure results from multiple categories
search = (Search()
    .where(K("in_stock") == True)
    .rank(Knn(query="wireless headphones", limit=100))
    .group_by(GroupBy(
        keys=K("category"),
        aggregate=MinK(keys=K.SCORE, k=2)  # Top 2 per category
    ))
    .limit(20)
    .select(K.DOCUMENT, K.SCORE, "name", "category", "price"))

results = collection.search(search)
rows = results.rows()[0]

# Results now include top 2 from each category instead of
# potentially all results from a single dominant category
for row in rows:
    print(f"{row['metadata']['name']}")
    print(f"  Category: {row['metadata']['category']}")
    print(f"  Price: ${row['metadata']['price']:.2f}")
    print(f"  Score: {row['score']:.3f}")
    print()

import { Search, K, Knn, GroupBy, MinK } from 'chromadb';

// Diversified product search - ensure results from multiple categories
const search = new Search()
  .where(K("in_stock").eq(true))
  .rank(Knn({ query: "wireless headphones", limit: 100 }))
  .groupBy(new GroupBy(
    [K("category")],
    new MinK([K.SCORE], 2)  // Top 2 per category
  ))
  .limit(20)
  .select(K.DOCUMENT, K.SCORE, "name", "category", "price");

const results = await collection.search(search);
const rows = results.rows()[0];

// Results now include top 2 from each category instead of
// potentially all results from a single dominant category
for (const row of rows) {
  console.log(row.metadata?.name);
  console.log(`  Category: ${row.metadata?.category}`);
  console.log(`  Price: $${row.metadata?.price?.toFixed(2)}`);
  console.log(`  Score: ${row.score?.toFixed(3)}`);
  console.log();
}

Tips and Best Practices#

Set Knn limit high enough - The Knn limit determines the candidate pool before grouping. Set it high enough to include candidates from all groups you want represented.
Use MinK with scores - Since Chroma uses distance-based scoring (lower is better), use MinK with K.SCORE to get the most relevant results per group.
Use MaxK for user-defined metrics - For metadata fields where higher is better (ratings, popularity), use MaxK.
Combine with filtering - Use .where() to filter before grouping to reduce the candidate pool to relevant documents.
Account for group size variance - Groups may return fewer than k results if they don’t have enough matching documents.

Next Steps#

Learn about ranking expressions to control how documents are scored before grouping
See Filtering with Where to narrow down candidates before grouping
Explore batch operations to run multiple grouped searches at once

Link last verified June 7, 2026. View original ↗

Source: Chroma Docs

Link last verified: 2026-03-04