Where Filters ↗

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 where filter JSON syntax used in Chroma queries and searches.

Where filters allow you to filter records by metadata values and document content when querying or searching Chroma collections. Each SDK provides a DSL to build these filters, but they all compile to a JSON format that you can also construct directly.

For example, SDK code like this:

from chromadb import K

where_filter = K("category").eq("science") & K("year").gte(2020)

import { K } from 'chromadb';

const whereFilter = K("category").eq("science")
  .and(K("year").gte(2020));

use chroma_types::{Where, MetadataExpression, MetadataComparison,
                   PrimitiveOperator, MetadataValue};

let where_filter =
    Where::Metadata(MetadataExpression {
        key: "category".to_string(),
        comparison: MetadataComparison::Primitive(
            PrimitiveOperator::Equal,
            MetadataValue::Str("science".to_string()),
        ),
    }) & Where::Metadata(MetadataExpression {
        key: "year".to_string(),
        comparison: MetadataComparison::Primitive(
            PrimitiveOperator::GreaterThanOrEqual,
            MetadataValue::Int(2020),
        ),
    });

Gets compiled to this JSON:

{
  "$and": [
    {"category": {"$eq": "science"}},
    {"year": {"$gte": 2020}}
  ]
}

This reference describes the rules of the JSON format. You can construct this JSON directly, which is useful when building filters programmatically or in environments without SDK access. See the SDK references to learn more about the DSL.

JSON Format#

Basic Structure#

A single filter is constructed as an object with a single key in it:

Metadata filter:

{
  "field_name": {
    "$operator": "value"
  }
}

Document filter:

{
  "#document": {
    "$operator": "pattern"
  }
}

Logical operator:

These filters can be combined using $and and $or:

{
  "$and": [/* array of filters */]
}

{
  "$or": [/* array of filters */]
}

Operators#

Scalar Comparison Operators#

Set Operators#

These operators check if a metadata value is in (or not in) a provided list. The list must contain values of the same type.

$in and $nin require arrays of the same type (all strings, all ints, all floats, or all booleans).

Metadata Array Operators#

These operators check if an array metadata field contains (or does not contain) a specific scalar value. The metadata field must be an array type (string[], int[], float[], or boolean[]).

Important: $contains and $not_contains have different meanings depending on context:

• On metadata fields (e.g., {"tags": {"$contains": "tech"}}): Checks if the array metadata field contains the value
• On #document (e.g., {"#document": {"$contains": "text"}}): Checks if the document text contains the substring

Document Operators#

Logical Operators#

Rules#

1. Shorthand equality: Direct value assignment is equivalent to $eq:

   {"status": "active"}

   is equivalent to:

   {"status": {"$eq": "active"}}

2. Single field per object: Each filter object can contain only one field or one logical operator ($and/$or).

3. Single operator per field: For field dictionaries, only one operator is allowed per field.