You can specify filter conditions to filter documents. A filter expression is optional.
Syntax: filter:"expression". Expression=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.
Example:
filter:"price > 100": You can use this expression to query the documents in which the value of the price field is greater than 100.
filter:"ids=1": The ids field is a multi-value field. You can use this expression to query the documents in which the values of the ids field contain 1.
filter:"province!=\"Zhejiang\"": You can use this expression to query the documents in which the value of the province field is not Zhejiang.Examples
Specify multiple conditions
Syntax: filter:"Condition Logical operator Condition"
Condition: an intact 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 either one of the conditions. You can also enclose conditions for which you want to assign the highest priority with parentheses ().
Example:
filter:"price > 100 AND categoryId=10": You can use this expression to query the documents in which the value of the categoryId field is 10 and the value of the price field is greater than 100.
filter:"categoryId=100 OR categoryId=10": You can use this expression to query the documents in which the value of the categoryId field is 100 or 10.
filter:"(categoryId=100 OR categoryId=10) AND price > 100": You can use this expression to query the documents in which the value of the categoryId field is 100 or 10, and the value of the price field is greater than 100.Use arithmetic expressions to specify conditions
Syntax: filter:"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.
Example:
filter:"price*0.5 > 100": You can use this expression to query the documents in which the product of the value of the price field multiplied by 0.5 is greater than 100.
filter:"price-cost > 100": You can use this expression to query the documents in which the difference between the value of the price field and the value of the cost field is greater than 100.
filter:"(price*0.5 > 100) AND categoryId=10": You can use this expression to query the documents in which the product of the value of the price field multiplied by 0.5 is greater than 100 and the value of the categoryId field is 10.Use functions to specify conditions
Syntax: filter:"Function Relational operator Right operand"
Description: Function: a built-in function such as in or notin. For more information, see the "Built-in functions" section of this topic. If the function that you invoke returns values of the BOOLEAN type, you do not need to specify a relational operator in the filter expression. You can also specify a function as the right operand of a relational operator.
Example:
filter:"in(id,"1|2|3")": You can use this expression to query the documents in which the value of the id field is 1, 2, or 3.The following section describes how to use other built-in functions to specify conditions.
Built-in functions
distance
distance: returns the spherical distance between two points. In most cases, this function is used in distance calculation for a location-based service (LBS).
Example:
Search for shops within 10 kilometers from the coordinates of a user. In this example, the longitude and latitude of the user are 120.34256 and 30.56982. The lon and lat fields that are used in documents to specify the longitude and latitude of a shop must be configured as attribute fields.
filter:"distance(lon,lat,\"120.34256\",\"30.56982\")<10"contain and notcontain
Description:
contain: checks whether the values of the a field contain a value of the b field. The a field can be a single-value field or multi-value field.
notcontain: checks whether the values of the a field do not contain a value of the b field. The a field can be a single-value field or multi-value field.
Parameters:
contain(a,b)
a: specifies a single-value or multi-value field of the INT32, INT64, or STRING type.
b: specifies a constant string. The specified constants in the string are separated by vertical bars (
|). If the values of the a field match one of the specified constants, this function returns true.
notcontain(a,b)
a: specifies a single-value or multi-value field of the INT32, INT64, or STRING type.
b: specifies a constant string. The specified constants in the string are separated by vertical bars (
|. If the values of the a field do not match one of the specified constants, this function returns true.
Return values:
contain(a,b): This function returns values of the BOOLEAN type. Valid values: true and false. A value of true indicates that the values of the a field contain a value of the b field. A value of false indicates that the values of the a field do not contain a value of the b field.notcontain(a,b): This function returns values of the BOOLEAN type. Valid values: true and false. A value of true indicates that the values of the a field do not contain a value of the b field. A value of false indicates that the values of the a field contain a value of the b field.
Example:
Use the contain function to query the documents in which the values of the nid field contain 1, 2, or 3.
filter:"contain(nid, \"1|2|3\")"Use the notcontain to query the documents in which the values of the nid field do not contain 1, 2, or 3.
filter:"notcontain(nid, \"1|2|3\")"in and notin
in or notin: checks whether field values are in a specific list.
Example:
Query the documents in which the value of the type field is 1, 2, or 3. The type field must be of the INT type.
filter:"in(type, \"1|2|3\")"Query the documents in which the value of the type field is not 1, 2, or 3. The type field must be of the INT32 type.
filter:"notin(type, \"1|2|3\")"Usage notes
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 expression, 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 with double quotation marks ('') in a filter expression. 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.