5.2 KiB
Every point stored in InfluxDB has an associated timestamp. Use Flux to process and operate on timestamps to suit your needs.
- Convert timestamp format
- Calculate the duration between two timestamps
- Retrieve the current time
- Normalize irregular timestamps
- Use timestamps and durations together
{{% note %}} If you're just getting started with Flux queries, check out the following:
- Get started with Flux for a conceptual overview of Flux and parts of a Flux query.
- Execute queries to discover a variety of ways to run your queries. {{% /note %}}
Convert timestamp format
Unix nanosecond to RFC3339
Use the time() function
to convert a Unix nanosecond timestamp
to an RFC3339 timestamp.
time(v: 1568808000000000000)
// Returns 2019-09-18T12:00:00.000000000Z
RFC3339 to Unix nanosecond
Use the uint() function
to convert an RFC3339 timestamp to a Unix nanosecond timestamp.
uint(v: 2019-09-18T12:00:00.000000000Z)
// Returns 1568808000000000000
Calculate the duration between two timestamps
Flux doesn't support mathematical operations using time type values. To calculate the duration between two timestamps:
- Use the
uint()function to convert each timestamp to a Unix nanosecond timestamp. - Subtract one Unix nanosecond timestamp from the other.
- Use the
duration()function to convert the result into a duration.
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
to convert the duration to a string.
{{% /note %}}
Retrieve the current time
Current UTC time
Use the now() function to
return the current UTC time in RFC3339 format.
now()
{{% note %}}
now() is cached at runtime, so all instances of now() in a Flux script
return the same value.
{{% /note %}}
Current system time
Import the system package and use the system.time() function
to return the current system time of the host machine in RFC3339 format.
import "system"
system.time()
{{% note %}}
system.time() returns the time it is executed, so each instance of system.time()
in a Flux script returns a unique value.
{{% /note %}}
Normalize irregular timestamps
To normalize irregular timestamps, truncate all _time values to a specified unit
with the truncateTimeColumn() function.
This is useful in join()
and pivot()
operations where points should align by time, but timestamps vary slightly.
data
|> truncateTimeColumn(unit: 1m)
{{< flex >}} {{% flex-content %}} Input:
| _time | _value |
|---|---|
| 2020-01-01T00:00:49Z | 2.0 |
| 2020-01-01T00:01:01Z | 1.9 |
| 2020-01-01T00:03:22Z | 1.8 |
| 2020-01-01T00:04:04Z | 1.9 |
| 2020-01-01T00:05:38Z | 2.1 |
| {{% /flex-content %}} | |
| {{% flex-content %}} | |
| Output: |
| _time | _value |
|---|---|
| 2020-01-01T00:00:00Z | 2.0 |
| 2020-01-01T00:01:00Z | 1.9 |
| 2020-01-01T00:03:00Z | 1.8 |
| 2020-01-01T00:04:00Z | 1.9 |
| 2020-01-01T00:05:00Z | 2.1 |
| {{% /flex-content %}} | |
| {{< /flex >}} |
Use timestamps and durations together
Add a duration to a timestamp
date.add()
adds a duration to a specified time and returns the resulting time.
import "date"
date.add(d: 6h, to: 2019-09-16T12:00:00Z)
// Returns 2019-09-16T18:00:00.000000000Z
Subtract a duration from a timestamp
date.sub()
subtracts a duration from a specified time and returns the resulting time.
import "date"
date.sub(d: 6h, from: 2019-09-16T12:00:00Z)
// Returns 2019-09-16T06:00:00.000000000Z
Shift a timestamp forward or backward
The timeShift() function adds the specified duration of time to each value in time columns (_start, _stop, _time).
Shift forward in time:
from(bucket: "example-bucket")
|> range(start: -5m)
|> timeShift(duration: 12h)
Shift backward in time:
from(bucket: "example-bucket")
|> range(start: -5m)
|> timeShift(duration: -12h)