From 00356edd338613423ef497751b413f1dc06cce43 Mon Sep 17 00:00:00 2001 From: Jason Tedor Date: Wed, 29 Jun 2016 17:02:15 -0400 Subject: [PATCH] Clarify time units usage in docs This commit clarifies the distinction between supported time units for durations and supported time units for durations in the docs. Relates #19159 --- .../bucket/datehistogram-aggregation.asciidoc | 9 +++-- .../diversified-sampler-aggregation.asciidoc | 6 ++-- docs/reference/api-conventions.asciidoc | 36 +++++++++++-------- .../migrate_5_0/aggregations.asciidoc | 5 +++ .../migration/migrate_5_0/settings.asciidoc | 5 ++- 5 files changed, 36 insertions(+), 25 deletions(-) diff --git a/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc b/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc index 29ba5e49626..4d9147067ec 100644 --- a/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc +++ b/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc @@ -26,8 +26,9 @@ Requesting bucket intervals of a month. Available expressions for interval: `year`, `quarter`, `month`, `week`, `day`, `hour`, `minute`, `second` - -Fractional values are allowed for seconds, minutes, hours, days and weeks. For example 1.5 hours: +Time values can also be specified via abbreviations supported by <> parsing. +Note that fractional time values are not supported, but you can address this by shifting to another +time unit (e.g., `1.5h` could instead be specified as `90m`). [source,js] -------------------------------------------------- @@ -36,15 +37,13 @@ Fractional values are allowed for seconds, minutes, hours, days and weeks. For e "articles_over_time" : { "date_histogram" : { "field" : "date", - "interval" : "1.5h" + "interval" : "90m" } } } } -------------------------------------------------- -See <> for accepted abbreviations. - ==== Keys Internally, a date is represented as a 64 bit number representing a timestamp diff --git a/docs/reference/aggregations/bucket/diversified-sampler-aggregation.asciidoc b/docs/reference/aggregations/bucket/diversified-sampler-aggregation.asciidoc index 0307840d685..70412d2680a 100644 --- a/docs/reference/aggregations/bucket/diversified-sampler-aggregation.asciidoc +++ b/docs/reference/aggregations/bucket/diversified-sampler-aggregation.asciidoc @@ -153,5 +153,7 @@ In this situation an error will be thrown. The de-duplication logic in the diversify settings applies only at a shard level so will not apply across shards. ===== No specialized syntax for geo/date fields -Currently the syntax for defining the diversifying values is defined by a choice of `field` or `script` - there is no added syntactical sugar for expressing geo or date units such as "1w" (1 week). -This support may be added in a later release and users will currently have to create these sorts of values using a script. +Currently the syntax for defining the diversifying values is defined by a choice of `field` or +`script` - there is no added syntactical sugar for expressing geo or date units such as "7d" (7 +days). This support may be added in a later release and users will currently have to create these +sorts of values using a script. diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc index 4e487325829..26c1a7476ed 100644 --- a/docs/reference/api-conventions.asciidoc +++ b/docs/reference/api-conventions.asciidoc @@ -171,8 +171,18 @@ one or more maths expressions: * `-1d` - subtract one day * `/d` - round down to the nearest day -The supported <> are: `y` (year), `M` (month), `w` (week), -`d` (day), `h` (hour), `m` (minute), and `s` (second). +The supported time units differ than those supported by <> for durations. +The supported units are: + +[horizontal] +`y`:: years +`M`:: months +`w`:: weeks +`d`:: days +`h`:: hours +`H`:: hours +`m`:: minutes +`s`:: seconds Some examples are: @@ -348,21 +358,17 @@ of supporting the native JSON number types. [float] === Time units -Whenever durations need to be specified, eg for a `timeout` parameter, the -duration must specify the unit, like `2d` for 2 days. The supported units -are: +Whenever durations need to be specified, e.g. for a `timeout` parameter, the duration must specify +the unit, like `2d` for 2 days. The supported units are: [horizontal] -`y`:: Year -`M`:: Month -`w`:: Week -`d`:: Day -`h`:: Hour -`m`:: Minute -`s`:: Second -`ms`:: Milli-second -`micros`:: Micro-second -`nanos`:: Nano-second +`d`:: days +`h`:: hours +`m`:: minutes +`s`:: seconds +`ms`:: milliseconds +`micros`:: microseconds +`nanos`:: nanoseconds [[byte-units]] [float] diff --git a/docs/reference/migration/migrate_5_0/aggregations.asciidoc b/docs/reference/migration/migrate_5_0/aggregations.asciidoc index d9227e91385..287da1efb99 100644 --- a/docs/reference/migration/migrate_5_0/aggregations.asciidoc +++ b/docs/reference/migration/migrate_5_0/aggregations.asciidoc @@ -26,3 +26,8 @@ for `from` and `to` anymore. `size: 0` is no longer valid for the terms, significant terms and geohash grid aggregations. Instead a size should be explicitly specified with a number greater than zero. + +==== Fractional time values + +Fractional time values (e.g., 0.5s) are no longer supported. For example, this means when setting +date histogram intervals "1.5h" will be rejected and should instead be input as "90m". diff --git a/docs/reference/migration/migrate_5_0/settings.asciidoc b/docs/reference/migration/migrate_5_0/settings.asciidoc index 8a7c386acdb..ffe69aa3cfb 100644 --- a/docs/reference/migration/migrate_5_0/settings.asciidoc +++ b/docs/reference/migration/migrate_5_0/settings.asciidoc @@ -291,6 +291,5 @@ still defaults to `true` in that case. The unit 'w' representing weeks is no longer supported. -Fractional time values (e.g., 0.5s) are no longer supported. For -example, this means when setting timeouts "0.5s" will be rejected and -should instead be input as "500ms". +Fractional time values (e.g., 0.5s) are no longer supported. For example, this means when setting +timeouts "0.5s" will be rejected and should instead be input as "500ms".