Range query
editRange query
editReturns documents that contain terms within a provided range.
Example request
editThe following search returns documents where the age
field contains a term
between 10
and 20
.
response = client.search( body: { query: { range: { age: { gte: 10, lte: 20, boost: 2 } } } } ) puts response
res, err := es.Search( es.Search.WithBody(strings.NewReader(`{ "query": { "range": { "age": { "gte": 10, "lte": 20, "boost": 2.0 } } } }`)), es.Search.WithPretty(), ) fmt.Println(res, err)
GET /_search { "query": { "range": { "age": { "gte": 10, "lte": 20, "boost": 2.0 } } } }
Top-level parameters for range
edit-
<field>
-
(Required, object) Field you wish to search.
Parameters for <field>
edit-
gt
- (Optional) Greater than.
-
gte
- (Optional) Greater than or equal to.
-
lt
- (Optional) Less than.
-
lte
- (Optional) Less than or equal to.
-
format
-
(Optional, string) Date format used to convert
date
values in the query.By default, Elasticsearch uses the date
format
provided in the<field>
's mapping. This value overrides that mapping format.For valid syntax, see
format
.If a format or date value is incomplete, the range query replaces any missing components with default values. See Missing date components.
-
relation
-
(Optional, string) Indicates how the range query matches values for
range
fields. Valid values are:-
INTERSECTS
(Default) - Matches documents with a range field value that intersects the query’s range.
-
CONTAINS
- Matches documents with a range field value that entirely contains the query’s range.
-
WITHIN
- Matches documents with a range field value entirely within the query’s range.
-
-
time_zone
-
(Optional, string) Coordinated Universal Time (UTC) offset or IANA time zone used to convert
date
values in the query to UTC.Valid values are ISO 8601 UTC offsets, such as
+01:00
or -08:00
, and IANA time zone IDs, such asAmerica/Los_Angeles
.For an example query using the
time_zone
parameter, see Time zone inrange
queries.The
time_zone
parameter does not affect the date math value ofnow
.now
is always the current system time in UTC.However, the
time_zone
parameter does convert dates calculated usingnow
and date math rounding. For example, thetime_zone
parameter will convert a value ofnow/d
. -
boost
-
(Optional, float) Floating point number used to decrease or increase the relevance scores of a query. Defaults to
1.0
.You can use the
boost
parameter to adjust relevance scores for searches containing two or more queries.Boost values are relative to the default value of
1.0
. A boost value between0
and1.0
decreases the relevance score. A value greater than1.0
increases the relevance score.
Notes
editUsing the range
query with text
and keyword
fields
editRange queries on text
or keyword
fields will not be executed if
search.allow_expensive_queries
is set to false.
Using the range
query with date
fields
editWhen the <field>
parameter is a date
field data type, you can use
date math with the following parameters:
-
gt
-
gte
-
lt
-
lte
For example, the following search returns documents where the timestamp
field
contains a date between today and yesterday.
GET /_search { "query": { "range": { "timestamp": { "gte": "now-1d/d", "lte": "now/d" } } } }
Missing date components
editFor range queries and date range aggregations, Elasticsearch replaces missing date components with the following values. Missing year components are not replaced.
MONTH_OF_YEAR: 01 DAY_OF_MONTH: 01 HOUR_OF_DAY: 23 MINUTE_OF_HOUR: 59 SECOND_OF_MINUTE: 59 NANO_OF_SECOND: 999_999_999
For example, if the format is yyyy-MM
, Elasticsearch converts a gt
value of 2099-12
to 2099-12-01T23:59:59.999_999_999Z
. This date uses the provided year (2099
)
and month (12
) but uses the default day (01
), hour (23
), minute (59
),
second (59
), and nanosecond (999_999_999
).
Numeric date range value
editWhen no date format is specified and the range query is targeting a date field, numeric values are interpreted representing milliseconds-since-the-epoch. If you want the value to represent a year, e.g. 2020, you need to pass it as a String value (e.g. "2020") that will be parsed according to the default format or the set format.
Date math and rounding
editElasticsearch rounds date math values in parameters as follows:
-
gt
-
Rounds up to the first millisecond not covered by the rounded date.
For example,
2014-11-18||/M
rounds up to2014-12-01T00:00:00.000
, excluding the entire month of November. -
gte
-
Rounds down to the first millisecond.
For example,
2014-11-18||/M
rounds down to2014-11-01T00:00:00.000
, including the entire month. -
lt
-
Rounds down to the last millisecond before the rounded value.
For example,
2014-11-18||/M
rounds down to2014-10-31T23:59:59.999
, excluding the entire month of November. -
lte
-
Rounds up to the latest millisecond in the rounding interval.
For example,
2014-11-18||/M
rounds up to2014-11-30T23:59:59.999
, including the entire month.
Example query using time_zone
parameter
editYou can use the time_zone
parameter to convert date
values to UTC using a
UTC offset. For example:
$params = [ 'body' => [ 'query' => [ 'range' => [ 'timestamp' => [ 'time_zone' => '+01:00', 'gte' => '2020-01-01T00:00:00', 'lte' => 'now', ], ], ], ], ]; $response = $client->search($params);
resp = client.search( body={ "query": { "range": { "timestamp": { "time_zone": "+01:00", "gte": "2020-01-01T00:00:00", "lte": "now", } } } }, ) print(resp)
response = client.search( body: { query: { range: { timestamp: { time_zone: '+01:00', gte: '2020-01-01T00:00:00', lte: 'now' } } } } ) puts response
res, err := es.Search( es.Search.WithBody(strings.NewReader(`{ "query": { "range": { "timestamp": { "time_zone": "+01:00", "gte": "2020-01-01T00:00:00", "lte": "now" } } } }`)), es.Search.WithPretty(), ) fmt.Println(res, err)
const response = await client.search({ body: { query: { range: { timestamp: { time_zone: '+01:00', gte: '2020-01-01T00:00:00', lte: 'now' } } } } }) console.log(response)