From 6cea9c7def65ad6760ca17498d83b97b45c6d234 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Mon, 20 Sep 2021 10:24:46 -0400 Subject: [PATCH 01/12] [DOCS] Document `time_series_metric` mapping parameter Documents the `time_series_metric` mapping parameter added with PR #76766. --- .../types/aggregate-metric-double.asciidoc | 5 +++++ .../mapping/types/histogram.asciidoc | 8 ++++++++ docs/reference/mapping/types/numeric.asciidoc | 19 ++++++++++++++----- 3 files changed, 27 insertions(+), 5 deletions(-) diff --git a/docs/reference/mapping/types/aggregate-metric-double.asciidoc b/docs/reference/mapping/types/aggregate-metric-double.asciidoc index cc359fddbbc03..9d6901a91aabe 100644 --- a/docs/reference/mapping/types/aggregate-metric-double.asciidoc +++ b/docs/reference/mapping/types/aggregate-metric-double.asciidoc @@ -57,6 +57,11 @@ specify at least one value. Default metric sub-field to use for queries, scripts, and aggregations that don't use a sub-field. Must be a value from the `metrics` array. +include::numeric.asciidoc[tag=time_series_metric] ++ +For `aggregate_metric_double` fields, this parameter also accepts `counter`, +`gauge`, and `summary`. You can't update this parameter for existing fields. + [[aggregate-metric-double-uses]] ==== Uses diff --git a/docs/reference/mapping/types/histogram.asciidoc b/docs/reference/mapping/types/histogram.asciidoc index 0e4b56df53e01..8d76a864fd33b 100644 --- a/docs/reference/mapping/types/histogram.asciidoc +++ b/docs/reference/mapping/types/histogram.asciidoc @@ -24,6 +24,14 @@ per document. Nested arrays are not supported. * `histogram` fields do not support sorting. ======== +[[histogram-params]] +==== Parameters + +include::numeric.asciidoc[tag=time_series_metric] ++ +For `histogram` fields, this parameter accepts `histogram`. You can't update +this parameter for existing fields. + [[histogram-uses]] ==== Uses diff --git a/docs/reference/mapping/types/numeric.asciidoc b/docs/reference/mapping/types/numeric.asciidoc index 4b4be55a4947a..c589eb1e7ed6c 100644 --- a/docs/reference/mapping/types/numeric.asciidoc +++ b/docs/reference/mapping/types/numeric.asciidoc @@ -111,8 +111,6 @@ the data as both a `keyword` _and_ a numeric data type. The following parameters are accepted by numeric types: -[horizontal] - <>:: Try to convert strings to numbers and truncate fractions for integers. @@ -140,6 +138,10 @@ support this parameter. Should the field be searchable? Accepts `true` (default) and `false`. +<>:: + + Metadata about the field. + <>:: Accepts a numeric value of the same `type` as the field which is @@ -173,9 +175,16 @@ support this parameter. the <> field. Accepts `true` or `false` (default). -<>:: - - Metadata about the field. +// tag::time_series_metric[] +`time_series_metric`:: +For internal use by Elastic only. Marks the field as a time series metric. The +value is the metric type. Defaults to `null` (not a time series metric). +// end::time_series_metric[] ++ +For numeric fields, this parameter accepts `gauge` and `counter`. You can't +update this parameter for existing fields. ++ +`scaled_float` and `unsigned_long` fields don't support this parameter. [[scaled-float-params]] ==== Parameters for `scaled_float` From f257a39e4b780ea633a53c272cbd3b25f8d97633 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Mon, 20 Sep 2021 11:38:42 -0400 Subject: [PATCH 02/12] Remove stray `also` --- docs/reference/mapping/types/aggregate-metric-double.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/mapping/types/aggregate-metric-double.asciidoc b/docs/reference/mapping/types/aggregate-metric-double.asciidoc index 9d6901a91aabe..3cbd140afee19 100644 --- a/docs/reference/mapping/types/aggregate-metric-double.asciidoc +++ b/docs/reference/mapping/types/aggregate-metric-double.asciidoc @@ -59,8 +59,8 @@ don't use a sub-field. Must be a value from the `metrics` array. include::numeric.asciidoc[tag=time_series_metric] + -For `aggregate_metric_double` fields, this parameter also accepts `counter`, -`gauge`, and `summary`. You can't update this parameter for existing fields. +For `aggregate_metric_double` fields, this parameter accepts `counter`, `gauge`, +and `summary`. You can't update this parameter for existing fields. [[aggregate-metric-double-uses]] ==== Uses From ba9a93396926bffce5c29d89a4f4d44f11e0767f Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Mon, 20 Sep 2021 12:03:56 -0400 Subject: [PATCH 03/12] Formatting tweak --- docs/reference/mapping/types/numeric.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/mapping/types/numeric.asciidoc b/docs/reference/mapping/types/numeric.asciidoc index c589eb1e7ed6c..c09ad69740afb 100644 --- a/docs/reference/mapping/types/numeric.asciidoc +++ b/docs/reference/mapping/types/numeric.asciidoc @@ -178,7 +178,7 @@ support this parameter. // tag::time_series_metric[] `time_series_metric`:: For internal use by Elastic only. Marks the field as a time series metric. The -value is the metric type. Defaults to `null` (not a time series metric). +value is the metric type. Defaults to `null` (Not a time series metric). // end::time_series_metric[] + For numeric fields, this parameter accepts `gauge` and `counter`. You can't From 89c8dca689f650ffdbbee6f117468744aa0ae0a8 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Tue, 21 Sep 2021 09:43:54 -0400 Subject: [PATCH 04/12] Remove unscaled float and unsigned long limitation --- docs/reference/mapping/types/numeric.asciidoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/reference/mapping/types/numeric.asciidoc b/docs/reference/mapping/types/numeric.asciidoc index c09ad69740afb..82e4153ca78ad 100644 --- a/docs/reference/mapping/types/numeric.asciidoc +++ b/docs/reference/mapping/types/numeric.asciidoc @@ -183,8 +183,6 @@ value is the metric type. Defaults to `null` (Not a time series metric). + For numeric fields, this parameter accepts `gauge` and `counter`. You can't update this parameter for existing fields. -+ -`scaled_float` and `unsigned_long` fields don't support this parameter. [[scaled-float-params]] ==== Parameters for `scaled_float` From 56189cf1119d81e62290e6389d1821a46c24ac25 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Tue, 21 Sep 2021 09:46:33 -0400 Subject: [PATCH 05/12] Rename `dimension` to `time_series_dimension` --- docs/reference/mapping/types/keyword.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/mapping/types/keyword.asciidoc b/docs/reference/mapping/types/keyword.asciidoc index 15852f8a7daff..76f5931920aa3 100644 --- a/docs/reference/mapping/types/keyword.asciidoc +++ b/docs/reference/mapping/types/keyword.asciidoc @@ -57,7 +57,7 @@ The following parameters are accepted by `keyword` fields: [horizontal] // tag::dimension[] -`dimension`:: +`time_series_dimension`:: For internal use by Elastic only. Marks the field as a time series dimension. Accepts `true` or `false` (default). + From 807b3977288637d79820462ad27e2ea36c58306b Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Tue, 21 Sep 2021 09:48:52 -0400 Subject: [PATCH 06/12] Update `dimension` ref --- docs/reference/index-modules.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/index-modules.asciidoc b/docs/reference/index-modules.asciidoc index 4f31b7f7c3d1f..5c721311afeb5 100644 --- a/docs/reference/index-modules.asciidoc +++ b/docs/reference/index-modules.asciidoc @@ -334,7 +334,8 @@ pipeline attempts to change the `_index` field, the indexing request will fail. For internal use by Elastic only. Maximum number of time series dimensions for the index. Defaults to `16`. + -You can mark a field as a dimension using the `dimension` mapping parameter. +You can mark a field as a dimension using the `time_series_dimension` mapping +parameter. [[index-hidden]] `index.hidden`:: From b0b65c56cceef45a48cdeb675ad55ca45f5310bc Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Tue, 21 Sep 2021 10:13:33 -0400 Subject: [PATCH 07/12] Reorder mapping params --- docs/reference/mapping/types/ip.asciidoc | 4 +- docs/reference/mapping/types/keyword.asciidoc | 40 +++++++++---------- docs/reference/mapping/types/numeric.asciidoc | 10 ++--- 3 files changed, 26 insertions(+), 28 deletions(-) diff --git a/docs/reference/mapping/types/ip.asciidoc b/docs/reference/mapping/types/ip.asciidoc index 173f27df08ce5..3404ac9fed723 100644 --- a/docs/reference/mapping/types/ip.asciidoc +++ b/docs/reference/mapping/types/ip.asciidoc @@ -45,8 +45,6 @@ The following parameters are accepted by `ip` fields: [horizontal] -include::keyword.asciidoc[tag=dimension] - <>:: Should the field be stored on disk in a column-stride fashion, so that it @@ -95,6 +93,8 @@ include::keyword.asciidoc[tag=dimension] the <> field. Accepts `true` or `false` (default). +include::keyword.asciidoc[tag=dimension] + [[query-ip-fields]] ==== Querying `ip` fields diff --git a/docs/reference/mapping/types/keyword.asciidoc b/docs/reference/mapping/types/keyword.asciidoc index 76f5931920aa3..7d721fb5b9497 100644 --- a/docs/reference/mapping/types/keyword.asciidoc +++ b/docs/reference/mapping/types/keyword.asciidoc @@ -54,24 +54,6 @@ include::numeric.asciidoc[tag=map-ids-as-keyword] The following parameters are accepted by `keyword` fields: -[horizontal] - -// tag::dimension[] -`time_series_dimension`:: -For internal use by Elastic only. Marks the field as a time series dimension. -Accepts `true` or `false` (default). -+ -The <> -index setting limits the number of dimensions in an index. -+ -Dimension fields have the following constraints: -+ -* The `doc_values` and `index` mapping parameters must be `true`. -* Field values cannot be an <>. -// end::dimension[] -* Field values cannot be larger than 1024 bytes. -* The field cannot use a <>. - <>:: Should the field be stored on disk in a column-stride fashion, so that it @@ -107,6 +89,10 @@ Dimension fields have the following constraints: Defaults to `docs` but can also be set to `freqs` to take term frequency into account when computing scores. +<>:: + + Metadata about the field. + <>:: Whether field-length should be taken into account when scoring queries. @@ -161,9 +147,21 @@ Dimension fields have the following constraints: when building a query for this field. Accepts `true` or `false` (default). -<>:: - - Metadata about the field. +// tag::dimension[] +`time_series_dimension`:: +For internal use by Elastic only. Marks the field as a time series dimension. +Accepts `true` or `false` (default). ++ +The <> +index setting limits the number of dimensions in an index. ++ +Dimension fields have the following constraints: ++ +* The `doc_values` and `index` mapping parameters must be `true`. +* Field values cannot be an <>. +// end::dimension[] +* Field values cannot be larger than 1024 bytes. +* The field cannot use a <>. include::constant-keyword.asciidoc[] diff --git a/docs/reference/mapping/types/numeric.asciidoc b/docs/reference/mapping/types/numeric.asciidoc index 82e4153ca78ad..71a3c59328091 100644 --- a/docs/reference/mapping/types/numeric.asciidoc +++ b/docs/reference/mapping/types/numeric.asciidoc @@ -117,11 +117,6 @@ The following parameters are accepted by numeric types: Accepts `true` (default) and `false`. Not applicable for `unsigned_long`. Note that this cannot be set if the `script` parameter is used. -include::keyword.asciidoc[tag=dimension] -+ -Of the numeric field types, only `byte`, `short`, `integer`, and `long` fields -support this parameter. - <>:: Should the field be stored on disk in a column-stride fashion, so that it @@ -175,6 +170,11 @@ support this parameter. the <> field. Accepts `true` or `false` (default). +include::keyword.asciidoc[tag=dimension] ++ +Of the numeric field types, only `byte`, `short`, `integer`, and `long` fields +support this parameter. + // tag::time_series_metric[] `time_series_metric`:: For internal use by Elastic only. Marks the field as a time series metric. The From 8fb2f3359a7eebee82b475558f94246f7e4c9f9c Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Tue, 21 Sep 2021 10:50:02 -0400 Subject: [PATCH 08/12] Add required/optional + data type --- docs/reference/mapping/types/keyword.asciidoc | 4 ++-- docs/reference/mapping/types/numeric.asciidoc | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/reference/mapping/types/keyword.asciidoc b/docs/reference/mapping/types/keyword.asciidoc index 7d721fb5b9497..e25de411891ce 100644 --- a/docs/reference/mapping/types/keyword.asciidoc +++ b/docs/reference/mapping/types/keyword.asciidoc @@ -149,8 +149,8 @@ The following parameters are accepted by `keyword` fields: // tag::dimension[] `time_series_dimension`:: -For internal use by Elastic only. Marks the field as a time series dimension. -Accepts `true` or `false` (default). +(Optional, Boolean) For internal use by Elastic only. Marks the field as a time +series dimension. Defaults to `false`. + The <> index setting limits the number of dimensions in an index. diff --git a/docs/reference/mapping/types/numeric.asciidoc b/docs/reference/mapping/types/numeric.asciidoc index 71a3c59328091..9d0ef1ff29324 100644 --- a/docs/reference/mapping/types/numeric.asciidoc +++ b/docs/reference/mapping/types/numeric.asciidoc @@ -177,8 +177,9 @@ support this parameter. // tag::time_series_metric[] `time_series_metric`:: -For internal use by Elastic only. Marks the field as a time series metric. The -value is the metric type. Defaults to `null` (Not a time series metric). +(Optional, string) For internal use by Elastic only. Marks the field as a time +series metric. The value is the metric type. Defaults to `null` (Not a time +series metric). // end::time_series_metric[] + For numeric fields, this parameter accepts `gauge` and `counter`. You can't From 1652774c9975b0018627e8a9d557b0a52696ca8b Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Tue, 21 Sep 2021 11:01:02 -0400 Subject: [PATCH 09/12] Remove horizontal tag --- docs/reference/mapping/types/ip.asciidoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/reference/mapping/types/ip.asciidoc b/docs/reference/mapping/types/ip.asciidoc index 3404ac9fed723..9981da4318773 100644 --- a/docs/reference/mapping/types/ip.asciidoc +++ b/docs/reference/mapping/types/ip.asciidoc @@ -43,8 +43,6 @@ NOTE: You can also store ip ranges in a single field using an <>:: Should the field be stored on disk in a column-stride fashion, so that it From 8354931550b00ac97e855a453ae84bade809f78f Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Wed, 22 Sep 2021 16:09:25 -0400 Subject: [PATCH 10/12] Add constraint. Support `unsigned_long` dimensions --- docs/reference/mapping/types/numeric.asciidoc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/reference/mapping/types/numeric.asciidoc b/docs/reference/mapping/types/numeric.asciidoc index 9d0ef1ff29324..6645bd1e08bef 100644 --- a/docs/reference/mapping/types/numeric.asciidoc +++ b/docs/reference/mapping/types/numeric.asciidoc @@ -172,8 +172,10 @@ The following parameters are accepted by numeric types: include::keyword.asciidoc[tag=dimension] + -Of the numeric field types, only `byte`, `short`, `integer`, and `long` fields -support this parameter. +Of the numeric field types, only `byte`, `short`, `integer`, `long`, and +`unsigned_long` fields support this parameter. ++ +A numeric field can't be both a time series dimension and a time series metric. // tag::time_series_metric[] `time_series_metric`:: @@ -184,6 +186,8 @@ series metric). + For numeric fields, this parameter accepts `gauge` and `counter`. You can't update this parameter for existing fields. ++ +A numeric field can't be both a time series dimension and a time series metric. [[scaled-float-params]] ==== Parameters for `scaled_float` From 2d24b30817083ec272b06cb3c6c16c5afb0baf9a Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Wed, 22 Sep 2021 16:25:12 -0400 Subject: [PATCH 11/12] Note `doc_values` must be `true` for numeric metrics --- docs/reference/mapping/types/numeric.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/mapping/types/numeric.asciidoc b/docs/reference/mapping/types/numeric.asciidoc index 6645bd1e08bef..06d72ab6bce1e 100644 --- a/docs/reference/mapping/types/numeric.asciidoc +++ b/docs/reference/mapping/types/numeric.asciidoc @@ -187,6 +187,7 @@ series metric). For numeric fields, this parameter accepts `gauge` and `counter`. You can't update this parameter for existing fields. + +For numeric time series metrics, the `doc_values` parameter must be `true`. A numeric field can't be both a time series dimension and a time series metric. [[scaled-float-params]] From 8b9774aedfe8cbda45f38388ef869ab650a30ca3 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Wed, 22 Sep 2021 16:27:09 -0400 Subject: [PATCH 12/12] Reword. rewrap. --- docs/reference/mapping/types/numeric.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/mapping/types/numeric.asciidoc b/docs/reference/mapping/types/numeric.asciidoc index 06d72ab6bce1e..2beeca1079744 100644 --- a/docs/reference/mapping/types/numeric.asciidoc +++ b/docs/reference/mapping/types/numeric.asciidoc @@ -187,8 +187,8 @@ series metric). For numeric fields, this parameter accepts `gauge` and `counter`. You can't update this parameter for existing fields. + -For numeric time series metrics, the `doc_values` parameter must be `true`. -A numeric field can't be both a time series dimension and a time series metric. +For a numeric time series metric, the `doc_values` parameter must be `true`. A +numeric field can't be both a time series dimension and a time series metric. [[scaled-float-params]] ==== Parameters for `scaled_float`