All Products
Search

This Product

    OpenSearch:Result filtering - filter clause

    Document Center

    OpenSearch:Result filtering - filter clause

    Last Updated:Jun 23, 2026

    The `filter` clause filters search results based on field conditions. This topic covers the syntax, usage notes, and examples.

    Clause description

    The filtering feature narrows down the documents returned by the `query` clause based on specified conditions and returns the final result set.

    Syntax

    The format for a filter condition is `field=value`.

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

    • You can combine multiple filter conditions using the logical operators `AND` and `OR`, and group them with parentheses `()`. The logical operators must be in uppercase.

    Notes

    1. The `filter` clause is optional.

    2. Fields used in the `filter` clause must be configured as property fields in the application schema.

    3. Due to potential precision issues, you cannot perform exact equality checks on `FLOAT` and `DOUBLE` data types. For these types, use range conditions with `>` and `<` instead.

    4. Values for `LITERAL` type fields must be enclosed in double quotation marks ("") in the `filter` clause. Otherwise, error 6135 (constant expression type error) is returned. Relational operations are supported for `LITERAL` fields, but arithmetic operations are not.

    5. Feature functions such as the distance function can be used in filter clauses.

    6. For `LITERAL` type fields, filtering supports only the `=` (equals) and `!=` (not equals) operators. Relational operators such as `>` and `<` are not supported. `LITERAL` fields are not tokenized and therefore require an exact match.

    7. The `in` and `notin` operators check whether a field value exists in a specified list. These operators support `INT`, `LITERAL`, `FLOAT`, and `DOUBLE` types. They do not support `ARRAY`, `TEXT`, or fuzzy tokenization types. For more information, see in and notin.

    8. Tokenized field types, such as `TEXT` and `SHORT_TEXT`, cannot be configured as property fields. Only numeric and non-tokenized field types can be configured as property fields. Supported types include `INT`, `INT_ARRAY`, `FLOAT`, `FLOAT_ARRAY`, `DOUBLE`, `DOUBLE_ARRAY`, `LITERAL`, and `LITERAL_ARRAY`.

    Using functions

    • distance: Calculates the spherical distance between two points, typically for location-based services (LBS).

    Example:

    Find restaurants named `Waipojia` within 10 km of a user at location (120.34256, 30.56982). The `lon` and `lat` fields represent the longitude and latitude of the merchant, are stored in the document, and must be configured as property fields.

    query=default:'Grandma's Home'&&filter=distance(lon,lat,"120.34256","30.56982")

    • in_polygon: Checks whether a point is within a polygon, typically used to determine whether a location falls within a delivery area.

    Example:

    Determine whether a user at location (120.307234, 39.294245) is within a merchant's delivery area. The delivery area is defined in the `coordinates` field, and the query filters for merchants whose delivery area contains the user's location.

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

    • in_query_polygon: Checks if a point specified in a document is within a polygon specified in the query.

    Example:

    Search for `Waipojia` restaurants within the Intime shopping district, which is defined by the polygon (xA,yA,xB,Yb,xC,Yc;xD,yD,xE,yE,xF,yF,xG,yG). The merchant's location is stored in the `point` field.

    query=default:'Grandma's Home'&&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: Performs custom grouping on an `INT_ARRAY` field and runs a specified operation on the grouped values.

    Example:

    Find shops that are open during a specific time period. A document contains an `int64_array` field named `open_time`, where each value represents an open time interval. The high 32 bits of the int64 value represent the start time, and the low 32 bits represent the end time. To query for shops open from 14:00 to 15:30, convert the time to a minute-based interval starting from 00:00 on the same day. The period from 14:00 to 15:30 is represented as (840, 930).

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

    • fieldlen: Returns the length of a `LITERAL` type field.

    Example:

    Return documents where the `usr_name` field is not empty.

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

    • in/notin: Checks whether a field value is present in or absent from a specified list.

    Example:

    Query for documents that contain `iphone` and where the `type` field, which is an INT type, has a value of 1, 2, or 3.

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

    Query for documents that contain `iphone` and where the `type` field, which is an INT32 type, does not have a value of 1, 2, or 3.

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

    • multi_attr: Returns the value at a specified position in an array field.

    Example:

    A product has multiple prices, such as market price, discount price, and sales price, stored in the `prices` array field. The following query finds mobile phones with a sales price of less than 1,000.

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

    Examples

    1. An application has an `int32` field named `category`, where values represent different categories such as 1 for news and 2 for bbs. The following query finds documents that contain `Zheda` and belong to category 2 (bbs).

       query=default:'Zheda' AND category_search:'2'   // An index field named category_search was created for the category field.
  // or
 query=default:'Zheda'&&filter=category=2

    2. A book search application uses a `LITERAL_ARRAY` field named `tags` to store genre tags such as "palace drama", "suspense/horror", and "romance". The following query finds documents that contain "The Legend of Zhen Huan" and have the "palace drama" tag.

       query=default:'The Legend of Zhen Huan'&&filter=tags="palace drama"

    3. An E-commerce application has an `int32` field for `hit` (clicks), an `int32` field for `sale` (sales), and an `int64` field for `create_time`. The following query finds documents that contain "dress", where the sum of sales and clicks multiplied by a `rate` (offset rate) exceeds 10,000, and the creation time is earlier than 1402345600.

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