Filtering

Filters narrow search results to documents matching specific criteria. They use a SQL-like syntax that supports comparisons, logical operators, and set membership.

Overview

Pass a filter expression as a string in the filter parameter of a search, delete-by-filter, or faceting request. Only fields declared as filterable_attributes in the index schema can be used in filters.

text
const results = await idx.search('shoes', {
  filter: "brand = 'Nike' AND price < 15000",
});

Operators

ParameterTypeDescription
= optionalcomparisonEqual to. Works on strings, numbers, and booleans.
!= optionalcomparisonNot equal to.
> optionalcomparisonGreater than. Numbers only.
>= optionalcomparisonGreater than or equal to. Numbers only.
< optionalcomparisonLess than. Numbers only.
<= optionalcomparisonLess than or equal to. Numbers only.

Logical Operators

Combine conditions with AND and OR. Use parentheses to control evaluation order.

text
# AND - both conditions must match
brand = 'Nike' AND price < 15000

# OR - either condition matches
brand = 'Nike' OR brand = 'Adidas'

# Parentheses for grouping
(brand = 'Nike' OR brand = 'Adidas') AND price < 10000
Note
AND has higher precedence than OR. Use parentheses when mixing both to make the intent explicit.

IN Operator

Match documents where a field's value is one of several options. Equivalent to multiple OR conditions on the same field.

text
tags IN ('running', 'shoes', 'outdoor')

This is equivalent to:

text
tags = 'running' OR tags = 'shoes' OR tags = 'outdoor'

EXISTS Operator

Match documents where a field has any value (is not missing).

text
metadata EXISTS

Field Types

The operators available depend on the field type declared in filterable_attributes.

ParameterTypeDescription
string optionalfield_typeSupports = and != operators. Values must be quoted in single quotes.
number optionalfield_typeSupports all comparison operators (=, !=, >, >=, <, <=). Values are unquoted integers or floats.
boolean optionalfield_typeSupports = and != operators. Values are true or false (unquoted).

Examples

text
# Simple equality
brand = 'Nike'

# Numeric range
price >= 5000 AND price <= 15000

# Boolean
in_stock = true

# Multiple brands with price cap
brand IN ('Nike', 'Adidas', 'Puma') AND price < 20000

# Complex grouping
(category = 'shoes' OR category = 'boots') AND brand = 'Nike' AND price >= 5000

# Not equal
status != 'archived'

# Existence check
discount_price EXISTS AND discount_price < price

Grammar Reference

The complete filter syntax grammar in BNF notation:

text
filter     = or_expr
or_expr    = and_expr ('OR' and_expr)*
and_expr   = condition ('AND' condition)*
condition  = field operator value
           | field 'IN' '(' value (',' value)* ')'
           | field 'EXISTS'
           | '(' or_expr ')'
operator   = '=' | '!=' | '>' | '>=' | '<' | '<='
value      = string_literal | number | 'true' | 'false' | 'null'
string_literal = '\'' text '\''
field      = identifier  (alphanumeric, underscore, dot)