A filter clause narrows search results by applying field conditions on top of a query clause. It operates on attribute fields only.
Syntax
filter=<field><operator><value>Combine multiple conditions with logical operators:
filter=category=2 AND (hit+sale)*rate>10000Operators
| Type | Supported operators |
|---|---|
| Relational | >, <, =, <=, >=, != |
| Arithmetic | +, -, *, /, &, ^, | |
| Logical | AND, OR, () — must be uppercase |
| List membership | in(field, "v1|v2|v3"), notin(field, "v1|v2|v3") |
Constraints by field type
| Field type | Supported operators | Notes |
|---|---|---|
| INT, INT32, INT64 | All relational and arithmetic | Use in/notin for list membership checks (INT and INT32 only; see in and notin for supported types) |
| FLOAT, DOUBLE | >, <, <=, >=, != | Avoid = — floating-point precision makes exact equality unreliable |
| LITERAL | =, != only | LITERAL fields are not tokenized, so only exact match is supported; enclose values in double quotation marks, e.g., tags="palace" — omitting quotes returns error 6135: "The value type of the constant expression is invalid" |
| INT_ARRAY, FLOAT_ARRAY, DOUBLE_ARRAY, LITERAL_ARRAY | Relational and arithmetic | Use bit_struct for bit-level operations on INT_ARRAY elements |
| TEXT, SHORT_TEXT | Not supported | These types cannot be configured as attribute fields and cannot be used in filter clauses |
| ARRAY (generic) | Not supported for in/notin | Fields using an analyzer for fuzzy searches are also excluded from in/notin |
Notes:
A filter clause is optional.
All fields referenced in a filter clause must be configured as attribute fields in the application schema. Fields of type TEXT and SHORT_TEXT cannot be configured as attribute fields.
Functionality functions such as
distancecan be used in filter clauses for sorting.
Built-in functions
The following functions extend filtering beyond simple field comparisons.
distance — filter by geographic proximity
Returns the spherical distance between a stored location and a query point. Use this for location-based service (LBS) scenarios where you need to limit results to a geographic radius.
The lon and lat fields must be configured as attribute fields.
Example: Find KFC locations within 10 km of a user at longitude 120.34256, latitude 30.56982.
query=default:'KFC'&&sort=+distance(lon,lat,"120.34256","30.56982")in_polygon — filter by delivery area or service boundary
Checks whether a fixed point (supplied in the query) falls inside a polygon stored in a document field. Use this when each document defines a geographic area (such as a merchant's delivery radius) and you want to find areas that contain a specific user location.
Example: Find merchants whose delivery areas cover the user at coordinates (120.307234, 39.294245), where coordinates stores each merchant's delivery polygon.
query=default:'Foods'&&filter=in_polygon(coordinates, 120.307234, 39.294245)>0in_query_polygon — filter by a query-defined area
Checks whether a point stored in a document falls inside a polygon you define in the query. Use this when you want to search within a custom geographic boundary, such as a business district.
Polygon vertices are passed via kvpairs. The point field stores each document's geographic location.
Example: Find KFC locations inside the Yintai business district.
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\,yGbit_struct — filter by bit-packed integer arrays
Splits each 64-bit integer in an INT_ARRAY field into named bit ranges and evaluates a condition against them. Use this when a single field encodes multiple attributes (such as open and close times) packed into bit segments.
Example: Find stores open between 14:00 (840 minutes) and 15:30 (930 minutes). The open_time field is of type INT64_ARRAY. Each integer stores the opening time in bits 0–31 and the closing time in bits 32–63.
filter=bit_struct(open_time, "0-31,32-63","overlap,$1,$2,840,930")!=-1fieldlen — filter by field length
Returns the character length of a LITERAL field. Use this to exclude empty or overly long values.
Example: Return only documents where usr_name is not empty.
query=default:'Keyword'&&filter=fieldlen(usr_name)>0in and notin — filter by a list of values
Checks whether a field's value appears in (or is absent from) a pipe-separated list. Supported types: INT, LITERAL, FLOAT, DOUBLE. Not supported for ARRAY, TEXT, or fields using an analyzer.
For more information, see in and notin.
Example: Return documents containing "iphone" where the INT type field is 1, 2, or 3.
query=default:'iphone'&&filter=in(type, "1|2|3")Example: Exclude documents where the INT32 type field is 1, 2, or 3.
query=default:'iphone'&&filter=notin(type, "1|2|3")multi_attr — filter by a specific element in an array field
Returns the value at a given position in an array field. Use this when a field stores multiple values for different attributes (such as market price, discount price, and sales price) and you want to filter on one specific position.
Example: Find mobile phones whose sales price (position 2 in the price field) is under 1,000.
query=default:'Mobile phone'&&filter=multi_attr(price,2)<1000Examples
Filter by an INT field
The category field (INT32) uses 1 for news and 2 for BBS. To find documents about "Zhejiang University" in the BBS category, use either of the following:
query=default:'Zhejiang University' AND category_search:'2'query=default:'Zhejiang University'&&filter=category=2Filter by a LITERAL array field
In a novel search application, the tags field (STRING_ARRAY) stores genre tags such as "palace", "suspense and horror", and "romance". To find palace-genre results for "Empresses in the Palace":
query=default:'Empresses in the Palace'&&filter=tags="palace"Combine arithmetic and relational operators
In an e-commerce application, find dress products where the combined engagement score (hit + sale) * rate exceeds 10,000 and the listing was created before timestamp 1402345600:
query=default:'dress'&&filter=(hit+sale)*rate>10000 AND create_time<1402345600