A filter clause narrows search results by evaluating conditions against attribute fields. After a query clause retrieves candidate documents, the filter clause keeps only those that match the specified conditions.
Syntax
{
"filter": "<expression>"
}The filter clause is optional. The value is a string containing a logical expression, such as price > 100 AND categoryId = 10.
All fields used in a filter clause must be attribute fields defined in schema.json.Field type constraints
Before writing filter expressions, review the constraints for each field type:
| Field type | Supported operators | Notes |
|---|---|---|
| Numeric (INTEGER, FLOAT, DOUBLE) | > < = <= >= != | For FLOAT and DOUBLE, avoid =. Floating-point precision makes exact equality checks unreliable. Use > or < instead. |
| STRING | = != | Enclose values in double quotation marks ("). Escape double quotation marks that appear inside values. Cannot use > or <. Cannot use arithmetic operators. |
| Multi-value field | = != | Returns documents where the field contains the condition value, not where it equals it exactly. |
| BOOLEAN (function return) | (none required) | Built-in functions that return BOOLEAN do not require a relational operator. |
Expression syntax
Quick reference
| Goal | Expression | Result |
|---|---|---|
| Numeric comparison | price > 100 | Documents where price is greater than 100 |
| String exclusion | province != "Zhejiang" | Documents where province is not Zhejiang |
| Multi-value match | ids = 1 | Documents where the ids field contains 1 |
| AND combination | price > 100 AND categoryId = 10 | Documents matching both conditions |
| OR combination | categoryId = 100 OR categoryId = 10 | Documents matching either condition |
| Grouped OR with AND | (categoryId = 100 OR categoryId = 10) AND price > 100 | Documents in either category with price above 100 |
| Arithmetic in filter | price * 0.5 > 100 | Documents where half the price exceeds 100 |
| Field arithmetic | price - cost > 100 | Documents where the margin exceeds 100 |
| Built-in function | in(id,"1|2|3") | Documents where id is 1, 2, or 3 |
Single condition
<left operand> <relational operator> <right operand>Left operand: an attribute field or a constant (numeric or string)
Relational operator:
><=<=>=!=Right operand: an attribute field or a constant (numeric or string)
Examples:
price > 100
ids = 1
province != "Zhejiang"Multiple conditions
<condition> <logical operator> <condition>Logical operators:
AND,ORANDreturns documents matching both conditions.ORreturns documents matching either condition.
Use parentheses
()to control evaluation priority.
Examples:
price > 100 AND categoryId = 10
categoryId = 100 OR categoryId = 10
(categoryId = 100 OR categoryId = 10) AND price > 100Arithmetic in filter conditions
<left operand> <arithmetic operator> <right operand> <relational operator> <condition value>Arithmetic operators:
+-*/Left operand: an attribute field or a constant (numeric or string)
Right operand: an attribute field or a constant (numeric or string)
Condition value: an attribute field or a constant
Examples:
price * 0.5 > 100
price - cost > 100
(price * 0.5 > 100) AND categoryId = 10Built-in functions
<function> <relational operator> <right operand>Built-in functions such as in and notin can be used as the left operand. If the function returns a BOOLEAN value, omit the relational operator. A function can also appear as the right operand of a relational operator.
For the full list of built-in functions, see Built-in functions.
Example:
in(id,"1|2|3")This returns documents where the id field contains 1, 2, or 3.