elasticsearch/docs/reference/query-languages/query-dsl/query-dsl-range-query.md

---

navigation_title: "Range" mapped_pages:

• https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-range-query.html ---

Range query [query-dsl-range-query]

Returns documents that contain terms within a provided range.

Example request [range-query-ex-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 [range-query-top-level-params]

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

Parameters for <field> [range-query-field-params]

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, {{es}} uses the [date `format`](/reference/elasticsearch/mapping-reference/mapping-date-format.md) provided in the `<field>`'s
mapping. This value overrides that mapping format.

For valid syntax, see [`format`](/reference/elasticsearch/mapping-reference/mapping-date-format.md).

::::{warning} If a format or date value is incomplete, the range query replaces any missing components with default values. See Missing date components. ::::

$$$querying-range-fields$$$

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](#range-query-time-zone).

::::{note} 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](/reference/query-languages/query-dsl/query-filter-context.md#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 [range-query-notes]

Using the range query with text and keyword fields [ranges-on-text-and-keyword]

Range 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 [ranges-on-dates]

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

Missing date components [missing-date-components]

For range queries and date range aggregations, {{es}} 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, {{es}} 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 [numeric-date]

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.

Date math and rounding [range-query-date-math-rounding]

{{es}} 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.

Example query using time_zone parameter [range-query-time-zone]

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, {{es}} converts this date to 2019-12-31T23:00:00 UTC.
3. The time_zone parameter does not affect the now value.