OpenSearch:filter clause

A filter clause is used to search for documents in which users are interested based on query conditions. You can use a filter clause to filter documents that are queried by using a query clause to retrieve required documents.

Format of a filter condition: field=value

• Filter conditions support regular conditional operators, such as >, <, =, <=, >=, !=,in, and notin, and arithmetic operators, such as +, -, *, /, &, ^, and |.

• You can specify multiple filter conditions and connect them by using the following logical operators: AND, OR, and (). The logical operators must be uppercase.

1. A filter clause is optional.

2. The fields that you reference in the parameters of a filter clause must be configured as attribute fields when you define an application schema.

3. An exact equivalence cannot be checked for fields of the FLOAT and DOUBLE types due to precision issues. Use > and < in such scenarios.

4. You must use double quotation marks (") to enclose field values for fields of the LITERAL type in a filter clause. Otherwise, the error code 6135 and the following error message are returned: The value type of the constant expression is invalid. Fields of the LITERAL type support relational operations, but do not support arithmetic operations.

5. You can use functionality functions such as the distance function in a filter clause for sorting.

6. To filter fields of the LITERAL type, you can use only operators = (equal to) and != (not equal to), but cannot use relational operators such as > and <. Fields of the LITERAL type are not tokenized. Therefore, exact match is required.

7. You can use the in or notin function to check whether field values are in a specific list. Only fields of the INT, LITERAL, FLOAT, and DOUBLE types are supported. Fields of the ARRAY and TEXT types or types that use the analyzer for fuzzy searches are not supported. For more information, see in and notin.

8. You cannot create attribute fields by using fields of text types, such as TEXT and SHORT_TEXT. You can create attribute fields only by using fields of numeric types or non-text types, such as INT, INT_ARRAY, FLOAT, FLOAT_ARRAY, DOUBLE, DOUBLE_ARRAY, LITERAL, and LITERAL_ARRAY.

• distance: returns the spherical distance between two points. Generally, this function is used in distance calculation for a location-based service (LBS).

Example:

Search for KFCs within 10 kilometers from the coordinates of a user. In this example, the longitude and latitude of the coordinates of the user are 120.34256 and 30.56982. The lon and lat fields that indicate the longitude and latitude of a KFC must be configured as attribute fields.

query=default:'KFC'&&sort=+distance(lon,lat,"120.34256","30.56982")

• in_polygon: checks whether a point is within a specific polygon geographic area. Generally, this function is used to determine whether a user is within the delivery radius of a merchant.

Example:

Check whether a user is within the delivery radii of merchants. For example, the coordinates field indicates the delivery radii of merchants, and the coordinates of a user are (120.307234, 39.294245). Then, you can use the following query clause to search for merchants whose delivery radii include the user:

query=default:'Foods'&&filter=in_polygon(coordinates, 120.307234, 39.294245)>0

• in_query_polygon: checks whether a point specified in a document is within a specific polygon geographic area.

Example:

Search for KFCs in the Yintai business district (xA,yA,xB,Yb,xC,Yc;xD,yD,xE,yE,xF,yF,xG,yG). The point field is used to store the geographic location of KFCs.

query=default:'KFC'&&filter=in_query_polygon("polygons",point)>0&&kvpairs=polygons:xA\,yA\,xB\,Yb\,xC\,Yc;xD\,yD\,xE\,yE\,xF\,yF\,xG\,yG

• bit_struct: splits each value into multiple parts for a field of the INT_ARRAY type and performs a specific operation on the parts.

Example:

Search for the stores that are open in a specific period of time. Your document has the open_time field of the INT64_ARRAY type. Each 64-bit integer in the array indicates the business hours of a store. The first 32 bits of an integer indicate the time when the store is open. The last 32 bits of an integer indicate the time when the store is closed. If you want to search for stores that are open from 14:00 to 15:30, you must first convert each of the start time and end time to the number of minutes that have elapsed from 00:00 on the same day. In this example, 14:00 is converted to 840, and 15:30 is converted to 930.

filter=bit_struct(open_time, "0-31,32-63","overlap,$1,$2,840,930")!=-1

• fieldlen: calculates the length of a field of the LITERAL type.

Example:

Search for documents in which the value of the usr_name field is not empty.

query=default:'Keyword'&&filter=fieldlen(usr_name)>0

• in or notin: checks whether field values are in a specific list.

Example:

Retrieve documents that contain "iphone" and the type field whose value is 1, 2, or 3. The type field is of the INT type.

query=default:'iphone'&&filter=in(type, "1|2|3")

Retrieve documents that contain "iphone" and the type field whose value is not 1, 2, or 3. The type field is of the INT32 type.

query=default:'iphone'&&filter=notin(type, "1|2|3")

• multi_attr: returns the value at a specific position in an array field.

Example:

Commodities have multiple prices, including market prices, discount prices, and sales prices. The prices are recorded in the prices field. You can use the following query clause to search for mobile phones whose sales price is less than 1,000:

query=default:'Mobile phone'&&filter=multi_attr(price,2)<1000

1. The category field of the INT32 type in an application has values such as 1 (news) and 2 (bbs). You can use one of the following query clauses to search for documents that contain "Zhejiang University" and in which the category field is set to 2:

   query=default:'Zhejiang University' AND category_search:'2' // The index field category_search is created for the category field.
     // Or
    query=default:'Zhejiang University'&&filter=category=2

2. In an application that is used to search for novels, the tags field of the STRING_ARRAY type specifies the following tags based on the styles of novels: palace, suspense and horror, and romance. You can use the following query clause to search for documents that contain "Empresses in the Palace" and in which the tags field has a value of "palace":

   query=default:'Empresses in the Palace'&&filter=tags="palace"

3. The hit and sale fields of the INT32 type and the create_time field of the INT64 type exist in an e-commerce application. You can use the following query clause to search for documents that meet the following conditions: 1. The documents contain "dress". 2. The product of the value of the rate field and the sum of the values of the hit and sale fields exceeds 10000. 3. The value of the create_time field is less than 1402345600.

   query=default:'dress'&&filter=(hit+sale)*rate>10000 AND create_time<1402345600