--- 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`. ```console GET /_search { "query": { "range": { "age": { "gte": 10, "lte": 20, "boost": 2.0 } } } } ``` ## Top-level parameters for `range` [range-query-top-level-params] `` : (Required, object) Field you wish to search. ## Parameters for `` [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 ``'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](#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](https://en.wikipedia.org/wiki/List_of_UTC_time_offsets) or [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 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](/reference/elasticsearch/rest-apis/common-options.md#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](/reference/elasticsearch/rest-apis/common-options.md#date-math). 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`](/reference/elasticsearch/mapping-reference/text.md) or [`keyword`](/reference/elasticsearch/mapping-reference/keyword.md) fields will not be executed if [`search.allow_expensive_queries`](/reference/query-languages/querydsl.md#query-dsl-allow-expensive-queries) is set to false. ### Using the `range` query with `date` fields [ranges-on-dates] When the `` parameter is a [`date`](/reference/elasticsearch/mapping-reference/date.md) field data type, you can use [date math](/reference/elasticsearch/rest-apis/common-options.md#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. ```console GET /_search { "query": { "range": { "timestamp": { "gte": "now-1d/d", "lte": "now/d" } } } } ``` #### Missing date components [missing-date-components] For range queries and [date range](/reference/aggregations/search-aggregations-bucket-daterange-aggregation.md) aggregations, {{es}} replaces missing date components with the following values. Missing year components are not replaced. ```text 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](/reference/elasticsearch/rest-apis/common-options.md#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: ```console 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.