OpenSearch:filter clause

The filter clause allows you to specify filter conditions based on your business requirements to search for documents. 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 common 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. The filter clause is optional.

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

3. 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 the filter clause, you can use an expression that includes a greater-than operator (>) and a smaller-than operator (<) to define the relationship.

4. You must enclose values of the LITERAL type in double quotation marks ('') in the filter clause. Fields of the LITERAL type support relational operations, but do not support arithmetic operations. If you do not enclose values of the LITERAL type in double quotation marks ('') in the filter clause, an error code 6135 and the following error message are returned: The value type of the constant expression is invalid.

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

6. You can use the equality operator (=) or inequality operator (!=) and cannot use the greater-than operator (>) or smaller-than operator (<) in an expression that contains fields of the LITERAL type. Fields of the LITERAL type are not segmented. 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, and 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. In most cases, 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'&&filter=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 merchants.

Example:

Check whether a user is within the delivery radius of merchants. For example, the coordinates field specifies the delivery radius 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 that support the delivery radius:

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 INT_ARRAY type. Each 64-bit integer in the array specifies the business hours of a store. The first 32 bits of an integer specify the time when the store is open. The last 32 bits of an integer specify 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 value 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 of a specific array field at a specific position.

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 the 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