TL;DR InfluxDB Tech Tips – Flux Timestamps

Navigate to:

In this post, we share some quick examples of how you can work with timestamps in Flux.

Q: What timestamp formats are available in Flux?

A: There are two timestamp formats available:

Unix timestamp

A Unix timestamp counts time since Unix Epoch (1970-01-01T00:00:00Z UTC) in specified units. The units are determined by the precision you set when writing data to InfluxDB.

InfluxDB supports the following Unix timestamp precisions:

Precision Description Example
ns Nanoseconds 1577836800000000000
us Microseconds 1577836800000000
ms Milliseconds 1577836800000
s Seconds 1577836800

The examples above represent 2020-01-01T00:00:00Z UTC

RFC3339 timestamp

An RFC3339 timestamp that uses the human readable DateTime format proposed in RFC 3339 (for example: 2020-01-01T00:00:00.00Z). Flux and InfluxDB clients return query results with RFC3339 timestamps.

Q: How do I convert the timestamp format?

A: To convert timestamps from Unix nanoseconds to a human readable RFC3339 timestamp, use the time() function.

time(v: 1568808000000000000)
// Returns 2019-09-18T12:00:00.000000000Z

To convert timestamps from RFC3339 to Unix nanoseconds, use the uint() function.

uint(v: 2019-09-18T12:00:00.000000000Z)
// Returns 1568808000000000000

Q: How do I calculate the duration between two timestamps?

A: 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

Q: How do I retrieve the current time?

A: To retrieve the current time in UTC, use the now() function. Note that the now() function is cached at runtime, so all instances of now() return the same value.


To retrieve the current system time of the host machine in RFC3339 format, import the system package and the system.time() function:

import "system"