Range query

Returns documents that contain terms within a provided range.

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
      }
    }
  }
}

<field>
     (Required, object) Field you wish to search.

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.

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.

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.

Range queries on text or keyword fields will not be executed if search.allow_expensive_queries is set to false.

When 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"
      }
    }
  }
}

For 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).

When 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.

Elasticsearch 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 to 2014-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 to 2014-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 to 2014-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 to 2014-11-30T23:59:59.999,
     including the entire month.

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",        1
        "gte": "2020-01-01T00:00:00", 2
        "lte": "now"                  3
      }
    }
  }
}

1. Indicates that date values use a UTC offset of +01:00.
2. With a UTC offset of +01:00, Elasticsearch converts this date to 2019-12-31T23:00:00 UTC.
3. The time_zone parameter does not affect the now value.