You can specify filter conditions to filter documents. The filter clause is optional.
Syntax: filter:"expression", where the expression is in the format left_value relational_operator right_value
Left value: an attribute field or a constant value. The constant value can be a number or a string.
Relational operator: the supported operators are >, <, =, <=, >=, and !=.
Right value: an attribute field or a constant value. The constant value can be a number or a string.
Examples:
filter:"price > 100" filters documents whose price is greater than 100.
filter:"ids=1" ids is a multi-value field. This expression filters documents whose ids field contains 1.
filter:"province!=\"Zhejiang\"" filters documents whose province is not Zhejiang.Query examples
Combine multiple filter conditions
Syntax: filter:"condition logical_operator condition"
Condition: a complete relational expression, such as price > 100.
Logical operator: AND or OR. AND indicates that the conditions on both sides must be TRUE. OR indicates that only one of the conditions needs to be TRUE. You can also use () in the clause. Parentheses have the highest precedence.
Examples:
filter:"price > 100 AND categoryId=10" filters documents whose categoryId is 10 and whose price is greater than 100.
filter:"categoryId = 100 OR categoryId=10" filters documents whose categoryId is 100 or 10.
filter:"(categoryId = 100 OR categoryId=10) AND price > 100" filters documents whose categoryId is 100 or 10 and whose price is greater than 100.Use arithmetic operations in filters
Syntax: filter:"left_value arithmetic_operator right_value relational_operator condition_value"
Left value: an attribute field or a constant value. The constant value can be a number or a string.
Arithmetic operator: the supported operators are +, -, *, and /.
Right value: an attribute field or a constant value. The constant value can be a number or a string.
Condition value: an attribute field or a constant value.
Examples:
filter:"price*0.5 > 100" filters documents whose price is greater than 100 after a 50% discount.
filter:"price-cost > 100" filters documents whose price minus cost is greater than 100.
filter:"(price*0.5 > 100) AND categoryId=10" filters documents whose price is greater than 100 after a 50% discount and whose categoryId is 10.Use functions in filters
Syntax: filter:"function relational_operator right_value"
Description: function is a built-in function, such as in or notin. For more information about built-in functions, see Built-in functions. If the return value of the function is of the Boolean type, the filter does not require a relational operator. In addition, the right side of the relational operator can also be a function.
Example:
filter:"in(id,"1|2|3")" filters documents whose id is 1, 2, or 3.For information about how to use other functions, see the Built-in functions section below.
Built-in functions
distance
distance: obtains the spherical distance between two points. This function is typically used to calculate distances in location-based services (LBS).
Example:
Query stores within 10 kilometers of the user at (120.34256,30.56982). lon and lat are the longitude and latitude of the store recorded in the document and must be configured as attribute fields.
filter:"distance(lon,lat,\"120.34256\",\"30.56982\")<10"contain/notcontain
Description:
contain: determines whether the single-value or multi-value a contains the content described in b.
notcontain: determines whether the single-value or multi-value a does not contain the content described in b.
Parameters:
contain(a,b)
a: a single-value or multi-value input of the int32, int64, or string type.
b: a constant string expression whose items are separated by
|. The condition is met if any one of the items is matched.
notcontain(a,b)
a: a single-value or multi-value input of the int32, int64, or string type.
b: a constant string expression whose items are separated by
|. The condition is met if the value does not match any of the items.
Return values:
contain(a,b): returns a Boolean value that indicates whether parameter a contains the set described in parameter b.notcontain(a,b): returns a Boolean value that indicates whether parameter a is not in the set described in parameter b.
Examples:
Use contain to retrieve all records whose nid field value is in [1,2,3].
filter:"contain(nid, \"1|2|3\")"Use notcontain to retrieve all records whose nid field value is not in [1,2,3].
filter:"notcontain(nid, \"1|2|3\")"in/notin
in and notin: determines whether a field value is (or is not) in the specified list.
Examples:
Query documents whose type (int type) is 1, 2, or 3:
filter:"in(type, \"1|2|3\")"Query documents whose type (int32 type) is not 1, 2, or 3:
filter:"notin(type, \"1|2|3\")"Usage notes
Exact equality comparisons cannot be performed on float and double values due to precision issues. In such scenarios, use > and < instead.
String field values must be enclosed in double quotation marks in filter expressions. All relational operations are supported, but arithmetic operations are not supported.
Filtering on string fields supports only the = and != operators, which mean equal to and not equal to. Relational operators such as > and < are not supported.
When = or != is used on a multi-value field, the semantics is that the condition is met as long as the multi-value field contains the value specified in the filter.
Double quotation marks in an expression must be escaped.