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
.
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
anddate
value are incomplete, Elasticsearch replaces any missing year, month, or date component with the start of Unix time, which is January 1st, 1970.For example, if the
format
value isdd
, Elasticsearch converts agte
value of10
to1970-01-10T00:00:00.000Z
.
-
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 date
fields
editWhen the <field>
parameter is a date
field datatype, 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", "lt" : "now/d" } } } }
Date math and rounding
editElasticsearch rounds date math values in parameters as follows:
-
gt
-
Rounds up to the lastest millisecond.
For example,
2014-11-18||/M
rounds up to2014-11-30T23:59:59.999
, excluding the entire month. -
gte
-
Rounds down to the first millisecond.
For example,
2014-11-18||/M
rounds down to2014-11-01
, including the entire month. -
lt
-
Rounds down to the first millisecond.
For example,
2014-11-18||/M
rounds down to2014-11-01
, excluding the entire month. -
lte
-
Rounds up to the lastest millisecond.
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: