Update Range mapping type docs #62112
Conversation
|
Pinging @elastic/es-docs (>docs) |
jrodewig
added
:Search Foundations/Mapping
|
Pinging @elastic/es-search (:Search/Mapping) |
1 similar comment
|
Pinging @elastic/es-search (:Search/Mapping) |
| @@ -4,6 +4,13 @@ | |||
| <titleabbrev>Range</titleabbrev> | |||
| ++++ | |||
|
|
|||
| A field that represents a relation between a lower and upper bound, using the | |||
There was a problem hiding this comment.
nit: might be just me, but I feel like the field doesn't represent the "relation" between the bounds but a continuous range of values between those bounds. The relations are then used to define and query the range. Maybe my understanding is off here, not a native speaker, sorry.
There was a problem hiding this comment.
I agree. I think a couple of high-level examples may make this a bit clearer:
Range field types represent a continuous range of values between an upper and
lower bound. For example, a range field can represent values like any integer
between 1 and 5 or any date in October.
| relations `gt`, `gte`, `lt` and `lte`. 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-bucket-range-aggregation.html[range] and |
There was a problem hiding this comment.
Just tried range aggregation on simple integer_range and date_range fields on 7.7 and master, gettting errors for both that these fields are not supported for this type of field. Maybe I'm missing something, what did you check or refer to when adding this?
| `date_range`:: A range of date values represented as unsigned 64-bit integer milliseconds elapsed since system epoch. | ||
| Date ranges accept the same formats described in the <<date, `date`>> type, but `now` is not allowed. |
There was a problem hiding this comment.
I think we can elaborate a little more for clarity.
| `date_range`:: A range of date values represented as unsigned 64-bit integer milliseconds elapsed since system epoch. | |
| Date ranges accept the same formats described in the <<date, `date`>> type, but `now` is not allowed. | |
| `date_range`:: | |
| A range of <<date,`date`>> values. Date ranges support various date formats | |
| through the <<mapping-date-format,`format`>> 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` <<date-math,date math>> expression are not supported. |
| relations `gt`, `gte`, `lt` and `lte`. 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-bucket-range-aggregation.html[range] and |
There was a problem hiding this comment.
I'd move the operators and common uses after the range types. I think many users will want to know what range types are available before getting info on how to define or use them.
| @@ -4,6 +4,13 @@ | |||
| <titleabbrev>Range</titleabbrev> | |||
| ++++ | |||
|
|
|||
| A field that represents a relation between a lower and upper bound, using the | |||
There was a problem hiding this comment.
I agree. I think a couple of high-level examples may make this a bit clearer:
Range field types represent a continuous range of values between an upper and
lower bound. For example, a range field can represent values like any integer
between 1 and 5 or any date in October.
There was a problem hiding this comment.
👍 LGTM. Thanks for the iteration @wylieconlon.
I'll merge and backport when @cbuescher approves.
Co-authored-by: Wylie Conlon <[email protected]>
Co-authored-by: Wylie Conlon <[email protected]>
The documentation for this mapping type was missing some important information about how to define and use ranges.