The filter clause

Clause description

The filter clause lets you filter documents based on filter conditions. It further filters the documents retrieved by the query clause to return the final results. The filter clause is optional.

Clause syntax

{
  "filter": ""
}

The filter clause is optional. Its value is a string that contains a logical expression composed of one or more filter conditions, such as `a > 10 AND b < 100`. For more information, see Expression syntax.

Expression syntax

Simple filtering

left operand relational operator right operand

Left operand: A property field or a constant value, such as a number or a string.

Relational operator: The supported operators are >, <, =, <=, >=, and !=.

Right operand: A property field or a constant value, such as a number or a string.

Examples:

price > 100 // Filters for documents where the price is greater than 100.
ids=1 // Filters for documents where the multi-value field 'ids' contains 1.
province != "Zhejiang" // Filters for documents where the province is not "Zhejiang".

Combining multiple filter conditions

condition logical operator condition

Condition: A complete relational expression, such as `price > 100`.

Logical operator: AND or OR. The AND operator requires both conditions to be true. The OR operator requires at least one condition to be true. You can also use parentheses `()` in the clause. Parentheses have the highest precedence.

Examples:

price > 100 AND categoryId=10 // Filters for documents where categoryId is 10 and the price is greater than 100.
categoryId = 100 OR categoryId=10 // Filters for documents where categoryId is 100 or 10.
(categoryId = 100 OR categoryId=10) AND price > 100 // Filters for documents where categoryId is 100 or 10, and the price is greater than 100.

Using arithmetic operations in filters

filter=left operand arithmetic operator right operand relational operator condition value

Left operand: A property field or a constant value, such as a number or a string.

Arithmetic operator: The supported operators are +, -, *, and /.

Right operand: A property field or a constant value, such as a number or a string.

Condition value: A property field or a constant value.

Examples:

price*0.5 > 100 // Filters for documents where 50% of the price is greater than 100.
price-cost > 100 // Filters for documents where the price minus the cost is greater than 100.
(price*0.5 > 100) AND categoryId=10 // Filters for documents where 50% of the price is greater than 100 and categoryId is 10.

Using functions in filters

function relational operator right operand

The `function` is a built-in function, such as `in` or `notin`. For more information, see Built-in functions. If a function returns a Boolean value, you do not need to include a relational operator in the filter. The right operand of a relational operator can also be a function.

Example:

in(id,"1|2|3") // Filters for documents where the ID is 1, 2, or 3.

Notes

• Fields used in a filter must be configured as property fields when you define the application schema.

• Because of precision issues, you cannot perform exact equality checks on `float` and `double` types. In these scenarios, use the `>` and `<` operators instead.

• String field values in a filter clause must be enclosed in double quotation marks. These fields do not support arithmetic operations.

• Filtering on string fields supports only the `=` (equal to) and `!=` (not equal to) operators. Other relational operators, such as `>` and `<`, are not supported.

• When you use the `=` or `!=` operator with a multi-value field, the semantics indicate that the field must contain the filter value.

• Double quotation marks in the expression must be escaped.