253 lines
5.9 KiB
Plaintext
253 lines
5.9 KiB
Plaintext
[[query-dsl-range-query]]
|
|
=== Range query
|
|
++++
|
|
<titleabbrev>Range</titleabbrev>
|
|
++++
|
|
|
|
Returns documents that contain terms within a provided range.
|
|
|
|
[[range-query-ex-request]]
|
|
==== Example request
|
|
|
|
The following search returns documents where the `age` field contains a term
|
|
between `10` and `20`.
|
|
|
|
[source,console]
|
|
----
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"range": {
|
|
"age": {
|
|
"gte": 10,
|
|
"lte": 20,
|
|
"boost": 2.0
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
[[range-query-top-level-params]]
|
|
==== Top-level parameters for `range`
|
|
|
|
`<field>`::
|
|
+
|
|
--
|
|
(Required, object) Field you wish to search.
|
|
--
|
|
|
|
[[range-query-field-params]]
|
|
==== 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, {es} uses the <<mapping-date-format,date `format`>> provided in the
|
|
`<field>`'s mapping. This value overrides that mapping format.
|
|
|
|
For valid syntax, see <<mapping-date-format,`format`>>.
|
|
|
|
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)
|
|
{wikipedia}/List_of_UTC_time_offsets[Coordinated Universal
|
|
Time (UTC) offset] or
|
|
{wikipedia}/List_of_tz_database_time_zones[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
|
|
<<range-query-time-zone,Time zone in `range` queries>>.
|
|
|
|
[NOTE]
|
|
====
|
|
The `time_zone` parameter does **not** affect the <<date-math,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,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,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-query-notes]]
|
|
==== Notes
|
|
|
|
[[ranges-on-text-and-keyword]]
|
|
===== Using the `range` query with `text` and `keyword` fields
|
|
Range queries on <<text, `text`>> or <<keyword, `keyword`>> fields will not be executed if
|
|
<<query-dsl-allow-expensive-queries, `search.allow_expensive_queries`>> is set to false.
|
|
|
|
[[ranges-on-dates]]
|
|
===== Using the `range` query with `date` fields
|
|
|
|
When the `<field>` parameter is a <<date,`date`>> field data type, you can use
|
|
<<date-math,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.
|
|
|
|
[source,console]
|
|
----
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"range": {
|
|
"timestamp": {
|
|
"gte": "now-1d/d",
|
|
"lt": "now/d"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
[[missing-date-components]]
|
|
====== Missing date components
|
|
|
|
For range queries and <<search-aggregations-bucket-daterange-aggregation,date
|
|
range>> aggregations, {es} replaces missing date components with the following
|
|
values. Missing year components are not replaced.
|
|
|
|
[source,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`).
|
|
|
|
[[range-query-date-math-rounding]]
|
|
====== Date math and rounding
|
|
{es} rounds <<date-math,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.
|
|
--
|
|
|
|
[[range-query-time-zone]]
|
|
===== 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:
|
|
|
|
[source,console]
|
|
----
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"range": {
|
|
"timestamp": {
|
|
"time_zone": "+01:00", <1>
|
|
"gte": "2020-01-01T00:00:00", <2>
|
|
"lte": "now" <3>
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
|
|
<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.
|