what is a range query, how to perform a range query - OpenSearch

Range queries filter results by numeric values, timestamps, or geographic coordinates. Typical applications include filtering products by price, finding records within a time window, and locating nearby merchants in online-to-offline (O2O) scenarios.

To run a range query, complete these steps in order:

Define the field type in the application schema.
Create a single-field index in the index schema with the correct analyzer.
Write a range query using the syntax for your field type.

Supported field types

Range queries support only three field types. Each field requires a dedicated single-field index — compound indexes are not supported for these types.

Field type	Description	Limit
`INT`	64-bit integer	Max 4 fields
`TIMESTAMP`	Integer timestamp in milliseconds (≥ 0). Storage precision is milliseconds, but query precision is seconds — the last three digits are treated as `000` during queries.	Max 4 fields
`GEO_POINT`	String in the format `lon lat`, where both values are doubles separated by a space. Longitude range: [−180, 180]. Latitude range: [−90, 90].	Max 2 fields

Create indexes

In the index schema, create a single-field index for each range-query field and assign the correct analyzer.

Field type	Analyzer	Index behavior
`INT`	Numeric analysis	No tokenization; builds a numeric index for range queries
`TIMESTAMP`	Numeric analysis	No tokenization; builds a numeric index for range queries
`GEO_POINT`	Geographic location	No tokenization; builds a numeric index for range queries

Query syntax

INT and TIMESTAMP

Both field types use the same bracket notation. Square brackets [ ] mean inclusive; parentheses ( ) mean exclusive. Omit a bound to leave that side open.

index:[number1,number2]   // number1 <= index <= number2
index:[number1,number2)   // number1 <= index < number2
index:(number1,number2]   // number1 < index <= number2
index:(number1,number2)   // number1 < index < number2
index:[number1,)          // index >= number1
index:(number1,)          // index > number1
index:(,number2]          // index <= number2
index:(,number2)          // index < number2

Do not place quotation marks immediately after the index colon.

Price range example — search for "dress" priced between 100 and 200:

query=index_text:'dress' AND index_price:[100,200]

Timestamp range example — search for news about "Beijing" from June 1 to June 3, 2019:

query=index_text:'Beijing' AND index_timestamp:[1559318400000,1559577599000]

Important

For numeric analysis indexes, the upper bound must be greater than or equal to the lower bound. A reversed range returns syntax error 6112 (Query clause error).

TIMESTAMP precision: Query precision is limited to seconds. The last three digits of any timestamp value are set to 000 during a query. The valid range is [0, 4102416000000], corresponding to 1970-01-01 00:00 through 2100-01-01 00:00. Values above the upper limit are clamped to 4102416000000. To differentiate values beyond this limit, use a filter.

GEO_POINT

Three spatial query shapes are supported: point, circle, and rectangle.

Point query — match documents at an exact coordinate:

query=spatial_index:'point(LON LAT)'

Example — find documents at coordinate (116.3906, 39.92324):

query=spatial_index:'point(116.3906 39.92324)'

Circle query — match documents within a radius of a center point:

query=spatial_index:'circle(LON LAT,Radius)'

Radius is in meters. Query performance is optimal for radii up to 10 km and degrades significantly beyond that.

Example — find documents within 1,000 meters of (116.5806, 39.99624):

query=spatial_index:'circle(116.5806 39.99624, 1000)'

Rectangle query — match documents within a bounding rectangle:

query=spatial_index:'rectangle(minX minY,maxX maxY)'

Latitude: maxY must be ≥ minY. If reversed, the system automatically corrects the order.
Longitude: The range from minX to maxX is interpreted west to east. If reversed, the query returns an incorrect range.

Example — find documents within the rectangle defined by (116.3906, 39.92324) and (116.3907, 39.92325):

query=spatial_index:'rectangle(116.3906 39.92324, 116.3907 39.92325)'

Valid GEO_POINT values are [−180, 180] for longitude and [−90, 90] for latitude.