[DOCS] Rewrite `range` query (#43282)

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

@@ -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`
+
+`<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.
 
-[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`
+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 the `<field>` parameter is a <<date,`date`>> field datatype, you can use
+<<date-math,date math>> with the following parameters:
 
-When running `range` queries on fields of type <<date,`date`>>, ranges can be
-specified using <<date-math>>:
+* `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.
 
-Rounding up moves to the last millisecond of the rounding scope, and rounding
-down to the first millisecond of the rounding scope. For example:
+[[range-query-date-math-rounding]]
+====== Date math and rounding
+{es} rounds <<date-math,date math>> values in parameters as follows:
 
-[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.