From 833300755967aa474a7ee72479fa09c8e207f0f2 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Thu, 19 Sep 2019 16:27:36 -0600 Subject: [PATCH 1/2] added timestamp manipulation guide, resolves #476 --- .../guides/manipulate-timestamps.md | 111 ++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 content/v2.0/query-data/guides/manipulate-timestamps.md diff --git a/content/v2.0/query-data/guides/manipulate-timestamps.md b/content/v2.0/query-data/guides/manipulate-timestamps.md new file mode 100644 index 000000000..bf6c1335d --- /dev/null +++ b/content/v2.0/query-data/guides/manipulate-timestamps.md @@ -0,0 +1,111 @@ +--- +title: Manipulate timestamps with Flux +description: > + Use Flux to process and manipulate timestamps. +menu: + v2_0: + name: Manipulate timestamps + parent: How-to guides +weight: 209 +--- + +Every point stored in InfluxDB has an associated timestamp. +Flux includes tools to process and manipulate timestamps to suit your needs. + +- [Timestamp conversions](#timestamp-conversions) +- [Common scenarios](#common-scenarios) +- [Time-related Flux functions](#time-related-flux-functions) + +## Timestamp conversions + +### Convert nanosecond epoch timestamp to RFC3339 +Use the [`time()` function](/v2.0/reference/flux/stdlib/built-in/transformations/type-conversions/time/) +to convert a **nanosecond** epoch timestamp to RFC3339 format. + +```js +time(v: 1568808000000000000) +// Returns 2019-09-18T12:00:00.000000000Z +``` + +### Convert RFC3339 timestamp to nanosecond epoch timestamp +Use the [`uint()` function](/v2.0/reference/flux/stdlib/built-in/transformations/type-conversions/unit/) +to convert an RFC3339 timestamp to a nanosecond epoch timestamp. + +```js +uint(v: 2019-09-18T12:00:00.000000000Z) +// Returns 1568808000000000000 +``` + +## Common scenarios + +### Calculate the duration between two timestamps +Flux doesn't support mathematical operations with time values. +To calculate the duration between two timestamps: + +1. Use the `uint()` function to convert each timestamp to a nanosecond epoch timestamp. +2. Subtract one nanosecond epoch timestamp from the other. +3. Use the `duration()` function to convert the result into a duration. + +```js +time1 = uint(v: 2019-09-17T21:12:05Z) +time2 = uint(v: 2019-09-18T22:16:35Z) + +duration(v: time2 - time1) +// Returns 25h4m30s +``` + +{{% note %}} +Flux doesn't support duration column types. +To store a duration in a column, use the [`string()` function](/v2.0/reference/flux/stdlib/built-in/transformations/type-conversions/string/) +to convert it to a string. +{{% /note %}} + +## Time-related Flux functions + +#### now() +Use the [`now()` function](/v2.0/reference/flux/stdlib/built-in/misc/now/) to +return the current UTC time in RFC3339 format. + +```js +now() +``` + +#### experimental.addDuration() +The [`experimental.addDuration()` function](/v2.0/reference/flux/stdlib/experimental/addduration/) +adds a duration to a specified time and returns the resulting time. + +{{% warn %}} +By using `experimental.addDuration()`, you accept the +[risks of experimental functions](/v2.0/reference/flux/stdlib/experimental/#use-experimental-functions-at-your-own-risk). +{{% /warn %}} + +```js +import "experimental" + +experimental.addDuration( + d: 6h, + to: 2019-09-16T12:00:00Z, +) + +// Returns 2019-09-16T18:00:00.000000000Z +``` + +#### experimental.subDuration() +The [`experimental.addDuration()` function](/v2.0/reference/flux/stdlib/experimental/subduration/) +subtracts a duration from a specified time and returns the resulting time. + +{{% warn %}} +By using `experimental.addDuration()`, you accept the +[risks of experimental functions](/v2.0/reference/flux/stdlib/experimental/#use-experimental-functions-at-your-own-risk). +{{% /warn %}} + +```js +import "experimental" + +experimental.subDuration( + d: 6h, + from: 2019-09-16T12:00:00Z, +) + +// Returns 2019-09-16T06:00:00.000000000Z +``` From 4d23e5c2b3514148b13e4fea23cd612622ab8a24 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Fri, 20 Sep 2019 09:09:03 -0600 Subject: [PATCH 2/2] updated timestamp guide with PR feedback --- .../guides/manipulate-timestamps.md | 23 ++++++++----------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/content/v2.0/query-data/guides/manipulate-timestamps.md b/content/v2.0/query-data/guides/manipulate-timestamps.md index bf6c1335d..c15afdf6f 100644 --- a/content/v2.0/query-data/guides/manipulate-timestamps.md +++ b/content/v2.0/query-data/guides/manipulate-timestamps.md @@ -10,24 +10,23 @@ weight: 209 --- Every point stored in InfluxDB has an associated timestamp. -Flux includes tools to process and manipulate timestamps to suit your needs. +Use Flux to process and manipulate timestamps to suit your needs. -- [Timestamp conversions](#timestamp-conversions) -- [Common scenarios](#common-scenarios) +- [Convert timestamp format](#convert-timestamp-format) - [Time-related Flux functions](#time-related-flux-functions) -## Timestamp conversions +## Convert timestamp format ### Convert nanosecond epoch timestamp to RFC3339 Use the [`time()` function](/v2.0/reference/flux/stdlib/built-in/transformations/type-conversions/time/) -to convert a **nanosecond** epoch timestamp to RFC3339 format. +to convert a **nanosecond** epoch timestamp to an RFC3339 timestamp. ```js time(v: 1568808000000000000) // Returns 2019-09-18T12:00:00.000000000Z ``` -### Convert RFC3339 timestamp to nanosecond epoch timestamp +### Convert RFC3339 to nanosecond epoch timestamp Use the [`uint()` function](/v2.0/reference/flux/stdlib/built-in/transformations/type-conversions/unit/) to convert an RFC3339 timestamp to a nanosecond epoch timestamp. @@ -36,10 +35,8 @@ uint(v: 2019-09-18T12:00:00.000000000Z) // Returns 1568808000000000000 ``` -## Common scenarios - ### Calculate the duration between two timestamps -Flux doesn't support mathematical operations with time values. +Flux doesn't support mathematical operations using [time type](/v2.0/reference/flux/language/types/#time-types) values. To calculate the duration between two timestamps: 1. Use the `uint()` function to convert each timestamp to a nanosecond epoch timestamp. @@ -57,12 +54,12 @@ duration(v: time2 - time1) {{% note %}} Flux doesn't support duration column types. To store a duration in a column, use the [`string()` function](/v2.0/reference/flux/stdlib/built-in/transformations/type-conversions/string/) -to convert it to a string. +to convert the duration to a string. {{% /note %}} ## Time-related Flux functions -#### now() +### Retrieve the current time Use the [`now()` function](/v2.0/reference/flux/stdlib/built-in/misc/now/) to return the current UTC time in RFC3339 format. @@ -70,7 +67,7 @@ return the current UTC time in RFC3339 format. now() ``` -#### experimental.addDuration() +### Add a duration to a timestamp The [`experimental.addDuration()` function](/v2.0/reference/flux/stdlib/experimental/addduration/) adds a duration to a specified time and returns the resulting time. @@ -90,7 +87,7 @@ experimental.addDuration( // Returns 2019-09-16T18:00:00.000000000Z ``` -#### experimental.subDuration() +### Subtract a duration from a timestamps The [`experimental.addDuration()` function](/v2.0/reference/flux/stdlib/experimental/subduration/) subtracts a duration from a specified time and returns the resulting time.