Docs
IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
Elasticsearch Reference [7.1] » Query DSL » Term-level queries » Range query
« Prefix query Regexp query »

Range query

Returns documents that contain terms within a provided range.

Example request

The 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

<field>

(Required, object) Field you wish to search.

Parameters for <field>

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 and date 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 is dd, Elasticsearch converts a gte value of 10 to 1970-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 as America/Los_Angeles.

For an example query using the time_zone parameter, see Time zone in range queries.

The time_zone parameter does not affect the date math value of now. now is always the current system time in UTC.

However, the time_zone parameter does convert dates calculated using now and date math rounding. For example, the time_zone parameter will convert a value of now/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 between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.

Notes

Using the range query with date fields

When 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

Elasticsearch rounds date math values in parameters as follows:

gt

Rounds up to the lastest millisecond.

For example, 2014-11-18||/M rounds up to 2014-11-30T23:59:59.999, excluding the entire month.

gte

Rounds down to the first millisecond.

For example, 2014-11-18||/M rounds down to 2014-11-01, including the entire month.

lt

Rounds down to the first millisecond.

For example, 2014-11-18||/M rounds down to 2014-11-01, excluding the entire month.

lte

Rounds up to the lastest millisecond.

For example, 2014-11-18||/M rounds up to 2014-11-30T23:59:59.999, including the entire month.

Example query using time_zone parameter

You can use the time_zone parameter to convert date values to UTC using a UTC offset. For example:

GET _search
{
    "query": {
        "range" : {
            "timestamp" : {
                "time_zone": "+01:00", 
                "gte": "2015-01-01 00:00:00", 
                "lte": "now" 
            }
        }
    }
}

Indicates that date values use a UTC offset of +01:00.

With a UTC offset of +01:00, Elasticsearch converts this date to 2014-12-31T23:00:00 UTC.

The time_zone parameter does not affect the now value.
« Prefix query Regexp query »