Skip to content

Commit 5f6321a

Browse files
jrodewigjrodewig
authored
[DOCS] Rewrite range query (#43282)
1 parent f130695 commit 5f6321a

File tree

1 file changed

+166
-102
lines changed

1 file changed

+166
-102
lines changed

‎docs/reference/query-dsl/range-query.asciidoc

Lines changed: 166 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11
[[query-dsl-range-query]]
22
=== Range Query
33

4-
Matches documents with fields that have terms within a certain range.
5-
The type of the Lucene query depends on the field type, for `string`
6-
fields, the `TermRangeQuery`, while for number/date fields, the query is
7-
a `NumericRangeQuery`. The following example returns all documents where
8-
`age` is between `10` and `20`:
4+
Returns documents that contain terms within a provided range.
5+
6+
[[range-query-ex-request]]
7+
==== Example request
8+
9+
The following search returns documents where the `age` field contains a term
10+
between `10` and `20`.
911

1012
[source,js]
11-
--------------------------------------------------
13+
----
1214
GET _search
1315
{
1416
"query": {
@@ -21,147 +23,209 @@ GET _search
2123
}
2224
}
2325
}
24-
--------------------------------------------------
26+
----
2527
// CONSOLE
2628

27-
The `range` query accepts the following parameters:
29+
[[range-query-top-level-params]]
30+
==== Top-level parameters for `range`
31+
32+
`<field>`::
33+
+
34+
--
35+
Field you wish to search.
36+
--
37+
38+
[[range-query-field-params]]
39+
==== Parameters for `<field>`
40+
41+
`gt`::
42+
Greater than. Optional.
43+
44+
`gte`::
45+
Greater than or equal to. Optional.
46+
47+
`lt`::
48+
Less than. Optional.
49+
50+
`lte`::
51+
Less than or equal to. Optional.
52+
53+
`format`::
54+
+
55+
--
56+
Date format used to convert `date` values in the query.
57+
58+
By default, {es} uses the <<mapping-date-format,date `format`>> provided in the
59+
`<field>`'s mapping. This value overrides that mapping format.
2860

29-
[horizontal]
30-
`gte`:: Greater-than or equal to
31-
`gt`:: Greater-than
32-
`lte`:: Less-than or equal to
33-
`lt`:: Less-than
34-
`boost`:: Sets the boost value of the query, defaults to `1.0`
61+
For valid syntax, see <<mapping-date-format,`format`>>. Optional.
3562

63+
[WARNING]
64+
====
65+
If a `format` and `date` value are incomplete, {es} replaces any missing year,
66+
month, or date component with the start of
67+
https://en.wikipedia.org/wiki/Unix_time[Unix time], which is January 1st, 1970.
68+
69+
For example, if the `format` value is `dd`, {es} converts a `gte` value of `10`
70+
to `1970-01-10T00:00:00.000Z`.
71+
====
72+
73+
--
74+
75+
[[querying-range-fields]]
76+
`relation`::
77+
+
78+
--
79+
Indicates how the range query matches values for `range` fields. Optional. Valid
80+
values are:
81+
82+
`INTERSECTS` (Default)::
83+
Matches documents with a range field value that intersects the query's range.
84+
85+
`CONTAINS`::
86+
Matches documents with a range field value that entirely contains the query's range.
87+
88+
`WITHIN`::
89+
Matches documents with a range field value entirely within the query's range.
90+
--
91+
92+
`time_zone`::
93+
+
94+
--
95+
https://en.wikipedia.org/wiki/List_of_UTC_time_offsets[Coordinated Universal
96+
Time (UTC) offset] or
97+
https://en.wikipedia.org/wiki/List_of_tz_database_time_zones[IANA time zone]
98+
used to convert `date` values in the query to UTC. Optional.
99+
100+
Valid values are ISO 8601 UTC offsets, such as `+01:00` or -`08:00`, and IANA
101+
time zone IDs, such as `America/Los_Angeles`.
102+
103+
For an example query using the `time_zone` parameter, see
104+
<<range-query-time-zone,Time zone in `range` queries>>.
105+
106+
[NOTE]
107+
====
108+
The `time_zone` parameter does **not** affect the <<date-math,date math>> value
109+
of `now`. `now` is always the current system time in UTC.
110+
111+
However, the `time_zone` parameter does convert dates calculated using `now` and
112+
<<date-math,date math rounding>>. For example, the `time_zone` parameter will
113+
convert a value of `now/d`.
114+
====
115+
--
116+
117+
`boost`::
118+
+
119+
--
120+
Floating point number used to decrease or increase the
121+
<<query-filter-context, relevance scores>> of a query. Default is `1.0`.
122+
Optional.
123+
124+
You can use the `boost` parameter to adjust relevance scores for searches
125+
containing two or more queries.
126+
127+
Boost values are relative to the default value of `1.0`. A boost value between
128+
`0` and `1.0` decreases the relevance score. A value greater than `1.0`
129+
increases the relevance score.
130+
--
131+
132+
[[range-query-notes]]
133+
==== Notes
36134

37135
[[ranges-on-dates]]
38-
==== Ranges on date fields
136+
===== Using the `range` query with `date` fields
137+
138+
When the `<field>` parameter is a <<date,`date`>> field datatype, you can use
139+
<<date-math,date math>> with the following parameters:
39140

40-
When running `range` queries on fields of type <<date,`date`>>, ranges can be
41-
specified using <<date-math>>:
141+
* `gt`
142+
* `gte`
143+
* `lt`
144+
* `lte`
145+
146+
For example, the following search returns documents where the `timestamp` field
147+
contains a date between today and yesterday.
42148

43149
[source,js]
44-
--------------------------------------------------
150+
----
45151
GET _search
46152
{
47153
"query": {
48154
"range" : {
49-
"date" : {
155+
"timestamp" : {
50156
"gte" : "now-1d/d",
51157
"lt" : "now/d"
52158
}
53159
}
54160
}
55161
}
56-
--------------------------------------------------
162+
----
57163
// CONSOLE
58164

59-
===== Date math and rounding
60-
61-
When using <<date-math,date math>> to round dates to the nearest day, month,
62-
hour, etc, the rounded dates depend on whether the ends of the ranges are
63-
inclusive or exclusive.
64165

65-
Rounding up moves to the last millisecond of the rounding scope, and rounding
66-
down to the first millisecond of the rounding scope. For example:
166+
[[range-query-date-math-rounding]]
167+
====== Date math and rounding
168+
{es} rounds <<date-math,date math>> values in parameters as follows:
67169

68-
[horizontal]
69170
`gt`::
171+
+
172+
--
173+
Rounds up to the lastest millisecond.
70174

71-
Greater than the date rounded up: `2014-11-18||/M` becomes
72-
`2014-11-30T23:59:59.999`, ie excluding the entire month.
175+
For example, `2014-11-18||/M` rounds up to `2014-11-30T23:59:59.999`, including
176+
the entire month.
177+
--
73178

74179
`gte`::
180+
+
181+
--
182+
Rounds down to the first millisecond.
75183

76-
Greater than or equal to the date rounded down: `2014-11-18||/M` becomes
77-
`2014-11-01`, ie including the entire month.
184+
For example, `2014-11-18||/M` rounds down to `2014-11-01`, excluding
185+
the entire month.
186+
--
78187

79188
`lt`::
189+
+
190+
--
191+
Rounds down to the first millisecond.
80192

81-
Less than the date rounded down: `2014-11-18||/M` becomes `2014-11-01`, ie
82-
excluding the entire month.
193+
For example, `2014-11-18||/M` rounds down to `2014-11-01`, excluding
194+
the entire month.
195+
--
83196

84197
`lte`::
198+
+
199+
--
200+
Rounds up to the lastest millisecond.
85201

86-
Less than or equal to the date rounded up: `2014-11-18||/M` becomes
87-
`2014-11-30T23:59:59.999`, ie including the entire month.
202+
For example, `2014-11-18||/M` rounds up to `2014-11-30T23:59:59.999`, including
203+
the entire month.
204+
--
88205

89-
===== Date format in range queries
206+
[[range-query-time-zone]]
207+
===== Example query using `time_zone` parameter
90208

91-
Formatted dates will be parsed using the <<mapping-date-format,`format`>>
92-
specified on the <<date,`date`>> field by default, but it can be overridden by
93-
passing the `format` parameter to the `range` query:
209+
You can use the `time_zone` parameter to convert `date` values to UTC using a
210+
UTC offset. For example:
94211

95212
[source,js]
96-
--------------------------------------------------
97-
GET _search
98-
{
99-
"query": {
100-
"range" : {
101-
"born" : {
102-
"gte": "01/01/2012",
103-
"lte": "2013",
104-
"format": "dd/MM/yyyy||yyyy"
105-
}
106-
}
107-
}
108-
}
109-
--------------------------------------------------
110-
// CONSOLE
111-
112-
Note that if the date misses some of the year, month and day coordinates, the
113-
missing parts are filled with the start of
114-
https://en.wikipedia.org/wiki/Unix_time[unix time], which is January 1st, 1970.
115-
This means, that when e.g. specifying `dd` as the format, a value like `"gte" : 10`
116-
will translate to `1970-01-10T00:00:00.000Z`.
117-
118-
===== Time zone in range queries
119-
120-
Dates can be converted from another timezone to UTC either by specifying the
121-
time zone in the date value itself (if the <<mapping-date-format, `format`>>
122-
accepts it), or it can be specified as the `time_zone` parameter:
123-
124-
[source,js]
125-
--------------------------------------------------
213+
----
126214
GET _search
127215
{
128216
"query": {
129217
"range" : {
130218
"timestamp" : {
131-
"gte": "2015-01-01 00:00:00", <1>
132-
"lte": "now", <2>
133-
"time_zone": "+01:00"
219+
"time_zone": "+01:00", <1>
220+
"gte": "2015-01-01 00:00:00", <2>
221+
"lte": "now" <3>
134222
}
135223
}
136224
}
137225
}
138-
--------------------------------------------------
226+
----
139227
// CONSOLE
140-
<1> This date will be converted to `2014-12-31T23:00:00 UTC`.
141-
<2> `now` is not affected by the `time_zone` parameter, its always the current system time (in UTC).
142-
However, when using <<date-math,date math rounding>> (e.g. down to the nearest day using `now/d`),
143-
the provided `time_zone` will be considered.
144-
145-
146-
[[querying-range-fields]]
147-
==== Querying range fields
148-
149-
`range` queries can be used on fields of type <<range,`range`>>, allowing to
150-
match a range specified in the query with a range field value in the document.
151-
The `relation` parameter controls how these two ranges are matched:
152-
153-
[horizontal]
154-
`WITHIN`::
155-
156-
Matches documents who's range field is entirely within the query's range.
157-
158-
`CONTAINS`::
159-
160-
Matches documents who's range field entirely contains the query's range.
161-
162-
`INTERSECTS`::
163-
164-
Matches documents who's range field intersects the query's range.
165-
This is the default value when querying range fields.
166-
167-
For examples, see <<range,`range`>> mapping type.
228+
<1> Indicates that `date` values use a UTC offset of `+01:00`.
229+
<2> With a UTC offset of `+01:00`, {es} converts this date to
230+
`2014-12-31T23:00:00 UTC`.
231+
<3> The `time_zone` parameter does not affect the `now` value.

0 commit comments

Comments
 (0)