Use a filter clause to narrow search results to documents that match specific field conditions. The filter clause runs after the query clause retrieves results, applying your conditions as a post-filter. It is optional.
Fields referenced in a filter clause must be declared as attribute fields in schema.json.
Syntax
All filter clauses follow this structure:
filter=<expression>An expression can be a simple comparison, a compound condition, an arithmetic expression, or a built-in function call.
Operators
| Type | Operators | Notes |
|---|---|---|
| Relational | > < = <= >= != | Compare a field value against a constant or another field |
| Arithmetic | + - * / | Apply arithmetic to a field before the relational comparison |
| Logical | AND OR | Combine multiple conditions |
Use parentheses () to assign the highest priority to the conditions you enclose.
Filter expressions
Single condition
filter=<field> <relational_operator> <value>The left and right operands can each be an attribute field or a constant (numeric or string).
| Example | Description |
|---|---|
filter=price > 100 | Documents where price is greater than 100 |
filter=ids=1 | Documents where the multi-value field ids contains 1 |
filter=province!= "Zhejiang" | Documents where province is not Zhejiang |
Multiple conditions
Combine conditions with AND or OR:
filter=<condition> AND|OR <condition>AND returns documents that match both conditions. OR returns documents that match either condition. Use parentheses to make evaluation order explicit when mixing AND and OR.
| Example | Description |
|---|---|
filter=price > 100 AND categoryId=10 | price greater than 100 and categoryId equals 10 |
filter=categoryId = 100 OR categoryId=10 | categoryId equals 100 or 10 |
filter=(categoryId = 100 OR categoryId=10) AND price > 100 | categoryId is 100 or 10, and price is greater than 100 |
Arithmetic expressions
Apply arithmetic to a field before comparing:
filter=<field> <arithmetic_operator> <value> <relational_operator> <condition_value>| Example | Description |
|---|---|
filter=price*0.5 > 100 | Documents where half of price exceeds 100 |
filter=price-cost > 100 | Documents where the margin (price minus cost) exceeds 100 |
filter=(price*0.5 > 100) AND categoryId=10 | Arithmetic condition combined with a category filter |
Functions
Use built-in functions such as in or notin as the left operand:
filter=<function> <relational_operator> <right_operand>If the function returns a BOOLEAN value, omit the relational operator. Functions can also appear as the right operand of a relational expression. For the full list of built-in functions, see Built-in functions.
| Example | Description |
|---|---|
filter=in(id,"1|2|3") | Documents where id is 1, 2, or 3 |
Usage notes
STRING fields
Enclose string values in double quotation marks:
province!= "Zhejiang".Only
=and!=are supported for STRING fields. The>,<, and arithmetic operators cannot be used with STRING fields.
FLOAT and DOUBLE fields
The system cannot check exact equality for FLOAT and DOUBLE values due to floating-point precision. Use a range expression that includes a greater-than operator (>) and a smaller-than operator (<) to define the relationship instead of using =.
Multi-value fields
When you use = or != with a multi-value field, the filter matches documents where the field contains the specified value — not where the field equals exactly that value.
filter=ids=1 # matches documents where the ids field includes 1