From 484e74ccaa4a6f7f560386b5ec6556a5eec8fc45 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Wed, 16 Sep 2020 09:33:04 -0400 Subject: [PATCH] [DOCS] Update range field type docs (#62112) (#62454) Co-authored-by: Wylie Conlon --- docs/reference/mapping/types/range.asciidoc | 31 +++++++++++++++------ 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/docs/reference/mapping/types/range.asciidoc b/docs/reference/mapping/types/range.asciidoc index 24ae7e85e7915..4d75b6d6ac144 100644 --- a/docs/reference/mapping/types/range.asciidoc +++ b/docs/reference/mapping/types/range.asciidoc @@ -4,6 +4,15 @@ Range ++++ +Range field types represent a continuous range of values between an upper and lower +bound. For example, a range can represent _any date in October_ or _any +integer from 0 to 9_. They are defined using the operators +`gt` or `gte` for the lower bound, and `lt` or `lte` for the upper bound. +They can be used for querying, and have +limited support for aggregations. The only supported aggregations are +{ref}/search-aggregations-bucket-histogram-aggregation.html[histogram], +{ref}/search-aggregations-metrics-cardinality-aggregation.html[cardinality]. + The following range types are supported: [horizontal] @@ -11,7 +20,11 @@ The following range types are supported: `float_range`:: A range of single-precision 32-bit IEEE 754 floating point values. `long_range`:: A range of signed 64-bit integers with a minimum value of +-2^63^+ and maximum of +2^63^-1+. `double_range`:: A range of double-precision 64-bit IEEE 754 floating point values. -`date_range`:: A range of date values represented as unsigned 64-bit integer milliseconds elapsed since system epoch. +`date_range`:: A range of <> values. Date ranges support various date formats + through the <> mapping parameter. Regardless of + the format used, date values are parsed into an unsigned 64-bit integer + representing milliseconds since the Unix epoch in UTC. Values containing the + `now` <> expression are not supported. `ip_range` :: A range of ip values supporting either {wikipedia}/IPv4[IPv4] or {wikipedia}/IPv6[IPv6] (or mixed) addresses. @@ -41,10 +54,10 @@ PUT range_index/_doc/1?refresh { "expected_attendees" : { <2> "gte" : 10, - "lte" : 20 + "lt" : 20 }, - "time_frame" : { <3> - "gte" : "2015-10-31 12:00:00", <4> + "time_frame" : { + "gte" : "2015-10-31 12:00:00", <3> "lte" : "2015-11-01" } } @@ -52,11 +65,11 @@ PUT range_index/_doc/1?refresh // TESTSETUP <1> `date_range` types accept the same field parameters defined by the <> type. -<2> Example indexing a meeting with 10 to 20 attendees. -<3> Date ranges accept the same format as described in <>. -<4> Example date range using date time stamp. This also accepts <> formatting. Note that "now" cannot be used at indexing time. +<2> Example indexing a meeting with 10 to 20 attendees, not including 20. +<3> Example date range using date time stamp. The following is an example of a <> on the `integer_range` field named "expected_attendees". +12 is a value inside the range, so it will match. [source,console] -------------------------------------------------- @@ -99,7 +112,7 @@ The result produced by the above query. "_score" : 1.0, "_source" : { "expected_attendees" : { - "gte" : 10, "lte" : 20 + "gte" : 10, "lt" : 20 }, "time_frame" : { "gte" : "2015-10-31 12:00:00", "lte" : "2015-11-01" @@ -161,7 +174,7 @@ This query produces a similar result: "_score" : 1.0, "_source" : { "expected_attendees" : { - "gte" : 10, "lte" : 20 + "gte" : 10, "lt" : 20 }, "time_frame" : { "gte" : "2015-10-31 12:00:00", "lte" : "2015-11-01"