Operate On Timestamps

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
• RFC3339 to Unix nanosecond

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:

1. Use the uint() function to convert each timestamp to a Unix nanosecond timestamp.
2. Subtract one Unix nanosecond timestamp from the other.
3. 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
• Current system 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:

Use timestamps and durations together

• Add a duration to a timestamp
• Subtract a duration from a timestamp

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)