Documentation

Work with time types

A time type represents a single point in time with nanosecond precision.

Type name: time

Time syntax

Time literals are represented by RFC3339 timestamps.

YYYY-MM-DD
YYYY-MM-DDT00:00:00Z
YYYY-MM-DDT00:00:00.000Z

Convert data types to time

Use the time() function to convert the following basic types to time:

time(v: "2021-01-01")
// Returns 2021-01-01T00:00:00.000000000Z

time(v: 1609459200000000000)
// Returns 2021-01-01T00:00:00.000000000Z

time(v: uint(v: 1609459200000000000))
// Returns 2021-01-01T00:00:00.000000000Z

Convert columns to time

Flux lets you iterate over rows in a stream of tables and convert columns to time.

To convert the _value column to time, use the toTime() function.

toTime() only operates on the _value column.

data
    |> toTime()
Given the following input data:
_time _value (int)
2021-01-01T00:00:00Z 10000000000
2021-01-01T02:00:00Z 20000000000
2021-01-01T03:00:00Z 30000000000
2021-01-01T04:00:00Z 40000000000
The example above returns:
_time _value (time)
2021-01-01T00:00:00Z 1970-01-01T00:00:10Z
2021-01-01T02:00:00Z 1970-01-01T00:00:20Z
2021-01-01T03:00:00Z 1970-01-01T00:00:30Z
2021-01-01T04:00:00Z 1970-01-01T00:00:40Z

To convert any column to time:

  1. Use map() to iterate over and rewrite rows.
  2. Use time() to convert columns values to time.
data
    |> map(fn: (r) => ({ r with epoch_ns: time(v: r.epoch_ns) }))
Given the following input data:
_time epoch_ns (int)
2021-01-01T00:00:00Z 10000000000
2021-01-01T02:00:00Z 20000000000
2021-01-01T03:00:00Z 30000000000
2021-01-01T04:00:00Z 40000000000
The example above returns:
_time epoch_ns (time)
2021-01-01T00:00:00Z 1970-01-01T00:00:10Z
2021-01-01T02:00:00Z 1970-01-01T00:00:20Z
2021-01-01T03:00:00Z 1970-01-01T00:00:30Z
2021-01-01T04:00:00Z 1970-01-01T00:00:40Z

Operate on time

Truncate timestamps to a specified unit

Truncating timestamps can be helpful when normalizing irregular timestamps. To truncate timestamps to a specified unit:

  1. Import the date package.
  2. Use date.truncate(), and provide the unit of time to truncate to.

Truncate to weeks

When truncating a time value to the week (1w), weeks are determined using the Unix epoch (1970-01-01T00:00:00Z UTC). The Unix epoch was on a Thursday, so all calculated weeks begin on Thursday.

t0 = 2021-01-08T14:54:10.023849Z

date.truncate(t: t0, unit: 1ms)
// Returns 2021-01-08T14:54:10.023000000Z

date.truncate(t: t0, unit: 1m)
// Returns 2021-01-08T14:54:00.000000000Z

date.truncate(t: t0, unit: 1w)
// Returns 2021-01-07T00:00:00.000000000Z

date.truncate(t: t0, unit: 1mo)
// Returns 2021-01-01T00:00:00.000000000Z

To truncate the _time column, use truncateTimeColumn():

data
    |> truncateTimeColumn(unit: 1m)
Given the following input data:
_time _value
2021-01-01T00:00:33Z 1.0
2021-01-01T00:01:10Z 1.1
2021-01-01T00:02:45Z 3.6
2021-01-01T00:03:23Z 2.5
The example above returns:
_time _value
2021-01-01T00:00:00Z 1.0
2021-01-01T00:01:00Z 1.1
2021-01-01T00:02:00Z 3.6
2021-01-01T00:03:00Z 2.5

Parse units of time from a timestamp

To parse a specific unit of time from a time value:

  1. Import the date package.
  2. Use functions in the date package to return specific units of time from a timestamp.
import "date"

t0 = 2021-01-08T14:54:10.023849Z

date.minute(t: t0)
// Returns 54

date.year(t: t0)
// Returns 2021

date.quarter(t: t0)
// Returns 1

Add a duration to a time value

To add a duration to a time value:

  1. Import the date package.
  2. Use date.add() to add a duration to a time value.
import "date"

date.add(d: 1w, to: 2021-01-01T00:00:00Z)
// Returns 2021-01-08T00:00:00.000000000Z

Subtract a duration from a time value

To subtract a duration from a time value:

  1. Import the date package.
  2. Use date.sub() to subtract a duration from a time value.
import "date"

date.sub(d: 1w, from: 2021-01-01T00:00:00Z)
// Returns 2020-12-25T00:00:00.000000000Z

Was this page helpful?

Thank you for your feedback!


The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more

InfluxDB v3 enhancements and InfluxDB Clustered is now generally available

New capabilities, including faster query performance and management tooling advance the InfluxDB v3 product line. InfluxDB Clustered is now generally available.

InfluxDB v3 performance and features

The InfluxDB v3 product line has seen significant enhancements in query performance and has made new management tooling available. These enhancements include an operational dashboard to monitor the health of your InfluxDB cluster, single sign-on (SSO) support in InfluxDB Cloud Dedicated, and new management APIs for tokens and databases.

Learn about the new v3 enhancements


InfluxDB Clustered general availability

InfluxDB Clustered is now generally available and gives you the power of InfluxDB v3 in your self-managed stack.

Talk to us about InfluxDB Clustered