A query clause is a required part of every query statement. It defines what to search for by binding a search query to one or more index fields. Use logical operators (AND, OR, ANDNOT, RANK) to combine multiple conditions and express complex retrieval logic.
Quick example — find documents whose title contains "OpenSearch" and are tagged "1":
query=title:'OpenSearch' AND tag:'1'Syntax
{
"query": "<query string>"
}The query field takes a string that pairs an index name with a search query. The sections below cover all supported query forms, from basic keyword searches to vector and hybrid queries.
Logical operators
All operators must be uppercase. When multiple operators appear in the same expression, they are evaluated in this order (lowest to highest precedence):
RANK < OR < AND < ANDNOT < ()Use parentheses to override default precedence. For example, default:'A' OR default:'B' AND default:'C' evaluates as default:'A' OR (default:'B' AND default:'C'). To match A-or-B first, write (default:'A' OR default:'B') AND default:'C'.
| Operator | Documents returned |
|---|---|
AND | Match both conditions |
OR | Match either condition |
ANDNOT | Match the left condition; exclude documents that match the right condition |
RANK | Match the left condition; the right condition affects relevance scores only, not which documents are returned |
() | Group conditions to control evaluation order |
Examples:
# Documents containing both "Mobile Phone" and "Bluetooth"
query=default:'Mobile Phone' AND default:'Bluetooth'
# Documents containing "Mobile Phone" or "Bluetooth"
query=default:'Mobile Phone' OR default:'Bluetooth'
# Documents containing "Mobile Phone" but not "Bluetooth"
query=default:'Mobile Phone' ANDNOT default:'Bluetooth'
# Documents containing "Mobile Phone", ranked higher if they also mention "Bluetooth"
query=default:'Mobile Phone' RANK default:'Bluetooth'Simple queries
<index name>:'<search query>'^<boost> <operator> <index name>:'<search query>'^<boost>| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| Index name | — | Yes | — | The index to search. The index must exist in the index schema. The system scans the field values the index is built on and returns matching documents. |
| Search query | — | Yes | — | The term or phrase to search for. |
boost | INT | No | 99 | Relevance weight for this condition. Valid values: 0–99. Higher values rank matching documents higher relative to other query clauses. |
Advanced queries
Multiple search queries on the same index
Use | (OR) or & (AND) to apply multiple search queries to the same index without repeating the index name:
<index name>:'<query1>'^boost | '<query2>'^boost
<index name>:'<query1>'^boost & '<query2>'^boostPhrase queries
Enclose the search query in double quotation marks to require an exact phrase match. All terms must appear adjacent and in the same order, both before and after analysis:
<index name>:"<search query>"^boostEscape double quotation marks when constructing the query clause programmatically.
Geography queries
Search documents by spatial location using the SPATIAL index type:
<index name>:'<SHAPE(ARGS...)>'Supported shapes:
| Shape | Syntax | Notes |
|---|---|---|
| Point | point(LON LAT) | Separate longitude and latitude with a space. |
| Circle | circle(LON LAT,Radius) | Radius is in meters. |
| Rectangle | rectangle(minLON minLAT,maxLON maxLAT) | maxLAT must be >= minLAT (auto-corrected if violated). minLON must be < maxLON (not auto-corrected; produces incorrect results if violated). |
| Polygon | polygon(LON1 LAT1,LON2 LAT2,...) | Convex and concave polygons supported. The start point and end point must be the same. Adjacent sides must not be collinear, and sides must not intersect. |
Usage notes:
The index must be of the SPATIAL type.
Enclose the shape expression in single quotation marks. Example:
query=spatial_index:'circle(130.0 10.0,1000.0)'Point coordinates for lines and polygons are projected onto a flat world map, regardless of whether they cross the 180° longitude line.
Inverted index results on the location field are accurate. Results on line and polygon fields require post-query filtering.
Range queries
Use bracket notation to query numeric or date ranges. Open endpoints (( )) are exclusive; closed endpoints ([ ]) are inclusive.
Numeric ranges — the index field must be a numeric type. Only integers are supported; floating-point values are not.
<index name>:(<start>,<end>]| Example | Matches |
|---|---|
query=price:(3,100) | price > 3 and price < 100 |
query=price:[3,100] | price >= 3 and price <= 100 |
query=price:(3,100] | price > 3 and price <= 100 |
query=price:(,100) | price < 100 (no lower bound) |
Date ranges — the index field must be of the DATE type. Timestamps must be INTEGER values in milliseconds.
<index name>:(<start_ms>,<end_ms>]| Boundary | Default value | Description |
|---|---|---|
| Start | 0 | If omitted, the scan starts from timestamp 0. |
| End | 4102416000000 | Represents 2100-01-01 00:00. If the value you specify exceeds this, the system uses 4102416000000. |
Examples
Text-based queries
# Title contains "Peking University"
query=title:'Peking University'
# Title contains both "Peking University" and "Zhejiang University"
query=title:'Peking University' AND title:'Zhejiang University'
# Title contains "Peking University" or "Zhejiang University"
query=title:'Peking University' OR title:'Zhejiang University'
# Products launched in October 2024 (timestamps in milliseconds)
query=publish_time:(1727712000000,1730304000000)Vector-based queries
All vector examples use the query=<vector index>:'<vector data>' pattern. For top N retrieval, append &n=<number> inside the query string.
# Query a 64-dimensional vector index
query=vector:'0.377796,-0.958450,0.409853,-0.238177,-1.293826,0.356797,-0.295727,0.847301,-1.220337,0.148032,-1.128458,0.903187,0.509352,0.293686,-1.005852,-0.488839,0.888227,-0.555556,-0.658025,0.267552,-0.567601,0.003045,0.591734,-0.515983,-1.316453,-1.462450,0.091946,1.554954,0.384802,0.720498,0.144338,1.217826,0.724039,0.044212,0.571332,-1.425430,0.618965,0.481887,-1.617787,1.505416,-0.683652,1.030900,0.562021,0.162437,0.816546,0.112229,-0.739288,-0.342643,-0.199292,0.508368,-1.384887,-1.842170,0.952622,-1.699499,0.199430,-0.232464,-0.273227,-0.383696,-0.511302,0.005458,1.873572,-0.926169,-0.417587,-0.660156'
# Return the top 10 nearest vectors
query=vector_index:'0.1,0.2,0.98,0.6;0.3,0.4,0.98,0.6&n=10'Hybrid queries (text + vector)
Combine keyword and vector conditions with AND to filter by text while ranking by vector similarity:
query=title:'Peking University' AND vector:'0.377796,-0.958450,0.409853,-0.238177,-1.293826,0.356797,-0.295727,0.847301,-1.220337,0.148032,-1.128458,0.903187,0.509352,0.293686,-1.005852,-0.488839,0.888227,-0.555556,-0.658025,0.267552,-0.567601,0.003045,0.591734,-0.515983,-1.316453,-1.462450,0.091946,1.554954,0.384802,0.720498,0.144338,1.217826,0.724039,0.044212,0.571332,-1.425430,0.618965,0.481887,-1.617787,1.505416,-0.683652,1.030900,0.562021,0.162437,0.816546,0.112229,-0.739288,-0.342643,-0.199292,0.508368,-1.384887,-1.842170,0.952622,-1.699499,0.199430,-0.232464,-0.273227,-0.383696,-0.511302,0.005458,1.873572,-0.926169,-0.417587,-0.660156'