OpenSearch:Filter clause

Overview

A filter clause filters documents based on specific conditions. After a query clause retrieves a set of documents, the filter clause refines the results. This clause is optional.

Syntax

{
  "filter": ""
}

The filter clause is optional. Its value is an expression string that consists 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: An attribute field or a constant (numeric or string).

Relational operator: Supported operators include >, <, =, <=, >=, and !=.

Right operand: An attribute field or a constant (numeric or string).

Examples:

price > 100: Returns documents where `price` is greater than 100.
ids = 1: `ids` is a `multi-value field`. Returns documents where the `ids` field contains the value 1.
province != "Zhejiang": Returns documents where `province` is not "Zhejiang".

Combining multiple conditions

condition logical_operator condition

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

Logical operator: AND or OR. AND requires both conditions to be true, while OR requires at least one condition to be true. You can also use parentheses () to group conditions, which have the highest precedence.

Examples:

price > 100 AND categoryId = 10: Returns documents where `categoryId` is 10 and `price` is greater than 100.
categoryId = 100 OR categoryId = 10: Returns documents where `categoryId` is either 100 or 10.
(categoryId = 100 OR categoryId = 10) AND price > 100: Returns documents where `categoryId` is 100 or 10, and `price` is greater than 100.

Arithmetic operations in filters

left_operand arithmetic_operator right_operand relational_operator condition_value

Left operand: An attribute field or a constant (numeric or string).

Arithmetic operator: Supported operators include +, -, *, and /.

Right operand: An attribute field or a constant (numeric or string).

Condition value: An attribute field or a constant.

Examples:

price * 0.5 > 100: Returns documents where `price` multiplied by 0.5 is greater than 100.
price - cost > 100: Returns documents where `price` minus `cost` is greater than 100.
(price * 0.5 > 100) AND categoryId = 10: Returns documents where `price` multiplied by 0.5 is greater than 100 and `categoryId` is 10.

Functions in filters

function relational_operator right_operand

Filters support functions, such as the built-in in or notin. For more information, see Built-in functions. If a function returns a boolean value, the relational operator is not required. A function can also serve as the right operand in a relational expression.

Example:

in(id,"1|2|3"): Returns documents where `id` is 1, 2, or 3.

Usage notes

• You must configure fields used in a filter clause as attribute fields in the schema.

• Due to floating-point precision issues, avoid using the equality operator (=) for exact comparisons on float and double fields. These comparisons are unreliable. Instead, use range comparisons with > and <.

• Enclose string field values in double quotation marks ("").

• String fields support only the equality (=) and inequality (!=) operators. They do not support other relational operators like > or < or arithmetic operations.

• When using the = operator with a multi-value field, the expression evaluates to true if the field contains the specified value. Conversely, != evaluates to true if the field does not contain the value.

• You must escape any double quotation marks (") that are part of a string value within the expression.