Skip to main content
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)
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

OperatorDescriptionValid TypesExample
$eqEqual tostring, int, float, boolean{"status": {"$eq": "active"}}
$neNot equal tostring, int, float, boolean{"count": {"$ne": 0}}
$gtGreater thanint, float{"price": {"$gt": 100}}
$gteGreater than or equalint, float{"rating": {"$gte": 4.5}}
$ltLess thanint, float{"stock": {"$lt": 10}}
$lteLess than or equalint, float{"discount": {"$lte": 0.25}}

​
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.
OperatorDescriptionValid List TypesExample
$inValue is in liststring[], int[], float[], boolean[]{"category": {"$in": ["tech", "ai"]}}
$ninValue is not in liststring[], int[], float[], boolean[]{"status": {"$nin": ["draft", "deleted"]}}
$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[]).
OperatorDescriptionValid TypesExample
$containsArray contains elementstring[], int[], float[], boolean[]{"tags": {"$contains": "tech"}}
$not_containsArray does not contain elementstring[], int[], float[], boolean[]{"tags": {"$not_contains": "deleted"}}
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

OperatorDescriptionValid OnExample
$containsDocument contains substring#document{"#document": {"$contains": "machine learning"}}
$not_containsDocument does not contain substring#document{"#document": {"$not_contains": "draft"}}
$regexDocument matches regex pattern#document{"#document": {"$regex": "quantum\\s+\\w+"}}
$not_regexDocument does not match regex pattern#document{"#document": {"$not_regex": "^draft"}}

​
Logical Operators

OperatorDescriptionExample
$andAll conditions must match{"$and": [{"status": "active"}, {"year": {"$gte": 2020}}]}
$orAny condition can match{"$or": [{"category": "tech"}, {"category": "science"}]}

​
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.