[DOCS] Rewrite `range` query (#43282)
This commit is contained in:
James Rodewig
parent
e738f0e6d2
commit
50eac875e4
|
|
@ -1,14 +1,16 @@
|
|||
[[query-dsl-range-query]]
|
||||
=== Range Query
|
||||
|
||||
Matches documents with fields that have terms within a certain range.
|
||||
The type of the Lucene query depends on the field type, for `string`
|
||||
fields, the `TermRangeQuery`, while for number/date fields, the query is
|
||||
a `NumericRangeQuery`. The following example returns all documents where
|
||||
`age` is between `10` and `20`:
|
||||
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,js]
|
||||
--------------------------------------------------
|
||||
----
|
||||
GET _search
|
||||
{
|
||||
"query": {
|
||||
|
|
@ -21,147 +23,209 @@ GET _search
|
|||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
----
|
||||
// CONSOLE
|
||||
|
||||
The `range` query accepts the following parameters:
|
||||
[[range-query-top-level-params]]
|
||||
==== Top-level parameters for `range`
|
||||
|
||||
[horizontal]
|
||||
`gte`:: Greater-than or equal to
|
||||
`gt`:: Greater-than
|
||||
`lte`:: Less-than or equal to
|
||||
`lt`:: Less-than
|
||||
`boost`:: Sets the boost value of the query, defaults to `1.0`
|
||||
`<field>`::
|
||||
+
|
||||
--
|
||||
Field you wish to search.
|
||||
--
|
||||
|
||||
[[range-query-field-params]]
|
||||
==== Parameters for `<field>`
|
||||
|
||||
`gt`::
|
||||
Greater than. Optional.
|
||||
|
||||
`gte`::
|
||||
Greater than or equal to. Optional.
|
||||
|
||||
`lt`::
|
||||
Less than. Optional.
|
||||
|
||||
`lte`::
|
||||
Less than or equal to. Optional.
|
||||
|
||||
`format`::
|
||||
+
|
||||
--
|
||||
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`>>. Optional.
|
||||
|
||||
[WARNING]
|
||||
====
|
||||
If a `format` and `date` value are incomplete, {es} replaces any missing year,
|
||||
month, or date component with the start of
|
||||
https://en.wikipedia.org/wiki/Unix_time[Unix time], which is January 1st, 1970.
|
||||
|
||||
For example, if the `format` value is `dd`, {es} converts a `gte` value of `10`
|
||||
to `1970-01-10T00:00:00.000Z`.
|
||||
====
|
||||
|
||||
--
|
||||
|
||||
[[querying-range-fields]]
|
||||
`relation`::
|
||||
+
|
||||
--
|
||||
Indicates how the range query matches values for `range` fields. Optional. 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`::
|
||||
+
|
||||
--
|
||||
https://en.wikipedia.org/wiki/List_of_UTC_time_offsets[Coordinated Universal
|
||||
Time (UTC) offset] or
|
||||
https://en.wikipedia.org/wiki/List_of_tz_database_time_zones[IANA time zone]
|
||||
used to convert `date` values in the query to UTC. Optional.
|
||||
|
||||
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`::
|
||||
+
|
||||
--
|
||||
Floating point number used to decrease or increase the
|
||||
<<query-filter-context, relevance scores>> of a query. Default is `1.0`.
|
||||
Optional.
|
||||
|
||||
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-dates]]
|
||||
==== Ranges on date fields
|
||||
===== Using the `range` query with `date` fields
|
||||
|
||||
When running `range` queries on fields of type <<date,`date`>>, ranges can be
|
||||
specified using <<date-math>>:
|
||||
When the `<field>` parameter is a <<date,`date`>> field datatype, 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,js]
|
||||
--------------------------------------------------
|
||||
----
|
||||
GET _search
|
||||
{
|
||||
"query": {
|
||||
"range" : {
|
||||
"date" : {
|
||||
"timestamp" : {
|
||||
"gte" : "now-1d/d",
|
||||
"lt" : "now/d"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
----
|
||||
// CONSOLE
|
||||
|
||||
===== Date math and rounding
|
||||
|
||||
When using <<date-math,date math>> to round dates to the nearest day, month,
|
||||
hour, etc, the rounded dates depend on whether the ends of the ranges are
|
||||
inclusive or exclusive.
|
||||
[[range-query-date-math-rounding]]
|
||||
====== Date math and rounding
|
||||
{es} rounds <<date-math,date math>> values in parameters as follows:
|
||||
|
||||
Rounding up moves to the last millisecond of the rounding scope, and rounding
|
||||
down to the first millisecond of the rounding scope. For example:
|
||||
|
||||
[horizontal]
|
||||
`gt`::
|
||||
+
|
||||
--
|
||||
Rounds up to the lastest millisecond.
|
||||
|
||||
Greater than the date rounded up: `2014-11-18||/M` becomes
|
||||
`2014-11-30T23:59:59.999`, ie excluding the entire month.
|
||||
For example, `2014-11-18||/M` rounds up to `2014-11-30T23:59:59.999`, including
|
||||
the entire month.
|
||||
--
|
||||
|
||||
`gte`::
|
||||
+
|
||||
--
|
||||
Rounds down to the first millisecond.
|
||||
|
||||
Greater than or equal to the date rounded down: `2014-11-18||/M` becomes
|
||||
`2014-11-01`, ie including the entire month.
|
||||
For example, `2014-11-18||/M` rounds down to `2014-11-01`, excluding
|
||||
the entire month.
|
||||
--
|
||||
|
||||
`lt`::
|
||||
+
|
||||
--
|
||||
Rounds down to the first millisecond.
|
||||
|
||||
Less than the date rounded down: `2014-11-18||/M` becomes `2014-11-01`, ie
|
||||
excluding the entire month.
|
||||
For example, `2014-11-18||/M` rounds down to `2014-11-01`, excluding
|
||||
the entire month.
|
||||
--
|
||||
|
||||
`lte`::
|
||||
+
|
||||
--
|
||||
Rounds up to the lastest millisecond.
|
||||
|
||||
Less than or equal to the date rounded up: `2014-11-18||/M` becomes
|
||||
`2014-11-30T23:59:59.999`, ie including the entire month.
|
||||
For example, `2014-11-18||/M` rounds up to `2014-11-30T23:59:59.999`, including
|
||||
the entire month.
|
||||
--
|
||||
|
||||
===== Date format in range queries
|
||||
[[range-query-time-zone]]
|
||||
===== Example query using `time_zone` parameter
|
||||
|
||||
Formatted dates will be parsed using the <<mapping-date-format,`format`>>
|
||||
specified on the <<date,`date`>> field by default, but it can be overridden by
|
||||
passing the `format` parameter to the `range` query:
|
||||
You can use the `time_zone` parameter to convert `date` values to UTC using a
|
||||
UTC offset. For example:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET _search
|
||||
{
|
||||
"query": {
|
||||
"range" : {
|
||||
"born" : {
|
||||
"gte": "01/01/2012",
|
||||
"lte": "2013",
|
||||
"format": "dd/MM/yyyy||yyyy"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
Note that if the date misses some of the year, month and day coordinates, the
|
||||
missing parts are filled with the start of
|
||||
https://en.wikipedia.org/wiki/Unix_time[unix time], which is January 1st, 1970.
|
||||
This means, that when e.g. specifying `dd` as the format, a value like `"gte" : 10`
|
||||
will translate to `1970-01-10T00:00:00.000Z`.
|
||||
|
||||
===== Time zone in range queries
|
||||
|
||||
Dates can be converted from another timezone to UTC either by specifying the
|
||||
time zone in the date value itself (if the <<mapping-date-format, `format`>>
|
||||
accepts it), or it can be specified as the `time_zone` parameter:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
----
|
||||
GET _search
|
||||
{
|
||||
"query": {
|
||||
"range" : {
|
||||
"timestamp" : {
|
||||
"gte": "2015-01-01 00:00:00", <1>
|
||||
"lte": "now", <2>
|
||||
"time_zone": "+01:00"
|
||||
"time_zone": "+01:00", <1>
|
||||
"gte": "2015-01-01 00:00:00", <2>
|
||||
"lte": "now" <3>
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
----
|
||||
// CONSOLE
|
||||
<1> This date will be converted to `2014-12-31T23:00:00 UTC`.
|
||||
<2> `now` is not affected by the `time_zone` parameter, its always the current system time (in UTC).
|
||||
However, when using <<date-math,date math rounding>> (e.g. down to the nearest day using `now/d`),
|
||||
the provided `time_zone` will be considered.
|
||||
|
||||
|
||||
[[querying-range-fields]]
|
||||
==== Querying range fields
|
||||
|
||||
`range` queries can be used on fields of type <<range,`range`>>, allowing to
|
||||
match a range specified in the query with a range field value in the document.
|
||||
The `relation` parameter controls how these two ranges are matched:
|
||||
|
||||
[horizontal]
|
||||
`WITHIN`::
|
||||
|
||||
Matches documents who's range field is entirely within the query's range.
|
||||
|
||||
`CONTAINS`::
|
||||
|
||||
Matches documents who's range field entirely contains the query's range.
|
||||
|
||||
`INTERSECTS`::
|
||||
|
||||
Matches documents who's range field intersects the query's range.
|
||||
This is the default value when querying range fields.
|
||||
|
||||
For examples, see <<range,`range`>> mapping type.
|
||||
<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
|
||||
`2014-12-31T23:00:00 UTC`.
|
||||
<3> The `time_zone` parameter does not affect the `now` value.
|
||||
Loading…
Reference in New Issue