Filtering

The filter_by parameter narrows search results using exact match, numeric range, boolean, geo radius, array, and nested operators. Filters use roaring bitmap intersections for fast execution.

Basic Syntax

filter_by=field_name:operator value

Operators

Boolean Operators

Combine filter conditions with && (AND) and || (OR):

# AND
filter_by=category:=Footwear && price:<100

# OR
filter_by=category:=Footwear || category:=Electronics

# Parentheses for grouping
filter_by=(category:=Footwear || category:=Electronics) && price:<100

Array Filters

Filter on array fields using OR (any match) or AND (all match) semantics:

# OR: document matches if any array element matches any listed value
filter_by=tags:=[red, blue]

# AND: document matches if array contains ALL listed values
filter_by=tags:=ALL[red, blue]

Boolean Filters

filter_by=in_stock:true
filter_by=in_stock:false

Geo Radius Filter

Filter documents within a radius of a geographic point. The unit (km or mi) is required:

# Within 50 kilometers
filter_by=location:(40.7128, -74.0060, 50 km)

# Within 30 miles
filter_by=location:(48.8566, 2.3522, 30 mi)

Geo Bounding Box Filter

Filter documents within a rectangular bounding box (4 coordinates: min_lat, min_lng, max_lat, max_lng):

filter_by=location:(40.70, -74.02, 40.80, -73.90)

Nested Element-Level AND

When enable_nested_fields is enabled on the collection, you can filter on multiple conditions within the same array element:

filter_by=variants:(color:=Black && size:=M)

This matches documents where at least one element in the variants array has both color equal to “Black” AND size equal to “M”. Without nested filtering, the conditions could match different array elements.

Example

Given a document with:

{
  "variants": [
    {"color": "Black", "size": "S"},
    {"color": "White", "size": "M"}
  ]
}

• variants:(color:=Black && size:=M) — does not match (no single element has both Black and M)
• variants.color:=Black && variants.size:=M — does match (conditions matched across different elements)

Multi-Value Exact Match

Match multiple values for the same field:

filter_by=category:=[Footwear, Electronics, Sports]

This is equivalent to category:=Footwear || category:=Electronics || category:=Sports.

Filter Length Limits

The filter_by expression is limited to 4,096 characters to prevent excessively complex queries.