OpenSearch:filter clause

Overview

You can specify conditions in a filter clause to query the documents that you want to obtain. After the system obtains the documents that you query by using a query clause, the system filters the documents based on the conditions that you specify in the filter clause and returns the documents that match the specified conditions.

Syntax

{
  "filter": ""
}

A filter clause is optional. The content of the filter clause is a string of logical expressions that contain various conditions, such as a > 10 AND b < 100. For more information, see the Expression syntax section of this topic.

Expression syntax

One filter condition

Left operand Relational operator Right operand

Left operand: an attribute field or a constant. The constant can be a numeric value or a string.

Relational operator: a relational operator. The following operators are supported: > < = <= >= !=

Right operand: an attribute field or a constant. The constant can be a numeric value or a string.

Examples:

price > 100: You can use this expression to query the documents whose values of the price field are greater than 100.
ids = 1: The ids field is a multi-value field. You can use this expression to query the documents whose values of the ids field contain 1.
province != "Zhejiang": You can use this expression to query the documents whose values of the province field are not Zhejiang.

Multiple filter conditions

Condition Logical operator Condition

Condition: a relational expression, such as price > 100.

Logical operator: the AND or OR operator. If you use the AND operator, the system returns the documents that match both conditions. If you use the OR operator, the system returns the documents that match one condition. You can also use parentheses () to enclose the conditions that you want to assign the highest priority.

Examples:

price > 100 AND categoryId = 10: You can use this expression to query the documents whose values of the price field are greater than 100 and values of the categoryId field are 10.
categoryId = 100 OR categoryId = 10: You can use this expression to query the documents whose values of the categoryId field are 100 or 10.
(categoryId = 100 OR categoryId = 10) AND price > 100: You can use this expression to query the documents whose values of the catergoryId field are 100 or 10 and values of the price field are greater than 100.

Filter conditions with arithmetic operations

Left operand Arithmetic operator Right operand Relational operator Condition value

Left operand: an attribute field or a constant. The constant can be a numeric value or a string.

Arithmetic operator: an arithmetic operator. The following operators are supported: + - * /

Right operand: an attribute field or a constant. The constant can be a numeric value or a string.

Condition value: an attribute field or a constant.

Examples:

price * 0.5 > 100: You can use this expression to query the documents whose values of the price field multiplied by 0.5 are greater than 100.
price - cost > 100: You can use this expression to query the documents whose values of the price field minus values of the cost field are greater than 100.
(price * 0.5 > 100) AND categoryId = 10: You can use this expression to query the documents whose values of the price field multiplied by 0.5 are greater than 100 and values of the categoryId field are 10.

Filter conditions with built-in functions

Function Relational operator Right operand

You can use built-in functions to specify conditions, such as in or notin. For information about more built-in functions, see Built-in functions. If the function that you invoke returns values of the BOOLEAN type, you do not need to specify a relational operator in the filter clause. You can also specify a function as the right operand of a relational operator.

Example:

in(id,"1|2|3"): You can use this expression to query the documents whose values of the id field are 1, 2, or 3.

Usage notes

• The fields that you specify in a filter clause must be the attribute fields that you specify in the schema.json file.

• The system cannot check whether a value of the FLOAT or DOUBLE type is equal to another value due to precision issues. If a field of the FLOAT or DOUBLE type is required in a filter clause, you can use an expression that contains a greater-than operator (>) or a smaller-than operator (<) to define the relationship.

• You must enclose values of the STRING type in double quotation marks ('' ") in a filter clause. You can specify a relational operator in an expression that contains a string to define the relationship between the string and another value. You cannot use an arithmetic operator to define the relationship between the string and another value.

• You can use the equality operator (=) or inequality operator (!=) in an expression that contains fields of the STRING type, but cannot use the greater-than operator (>) or smaller-than operator (<) in such an expression.

• If you use the equality operator (=) or inequality operator (!=) to define the relationship between a multi-value field and a condition value, the system returns the documents whose values of the multi-value field include the condition value.

• The double quotation marks (" ") in an expression must be escaped.