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:00Z10000000000
2021-01-01T02:00:00Z20000000000
2021-01-01T03:00:00Z30000000000
2021-01-01T04:00:00Z40000000000
The example above returns:
_time_value (time)
2021-01-01T00:00:00Z1970-01-01T00:00:10Z
2021-01-01T02:00:00Z1970-01-01T00:00:20Z
2021-01-01T03:00:00Z1970-01-01T00:00:30Z
2021-01-01T04:00:00Z1970-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:
_timeepoch_ns (int)
2021-01-01T00:00:00Z10000000000
2021-01-01T02:00:00Z20000000000
2021-01-01T03:00:00Z30000000000
2021-01-01T04:00:00Z40000000000
The example above returns:
_timeepoch_ns (time)
2021-01-01T00:00:00Z1970-01-01T00:00:10Z
2021-01-01T02:00:00Z1970-01-01T00:00:20Z
2021-01-01T03:00:00Z1970-01-01T00:00:30Z
2021-01-01T04:00:00Z1970-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:33Z1.0
2021-01-01T00:01:10Z1.1
2021-01-01T00:02:45Z3.6
2021-01-01T00:03:23Z2.5
The example above returns:
_time_value
2021-01-01T00:00:00Z1.0
2021-01-01T00:01:00Z1.1
2021-01-01T00:02:00Z3.6
2021-01-01T00:03:00Z2.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!


Linux Package Signing Key Rotation

All signed InfluxData Linux packages have been resigned with an updated key. If using Linux, you may need to update your package configuration to continue to download and verify InfluxData software packages.

For more information, see the Linux Package Signing Key Rotation blog post.

InfluxDB Cloud backed by InfluxDB IOx

All InfluxDB Cloud organizations created on or after January 31, 2023 are backed by the new InfluxDB IOx storage engine. Check the right column of your InfluxDB Cloud organization homepage to see which InfluxDB storage engine you’re using.

If powered by IOx, this is the correct documentation.

If powered by TSM, see the TSM-based InfluxDB Cloud documentation.

InfluxDB Cloud backed by InfluxDB TSM

All InfluxDB Cloud organizations created on or after January 31, 2023 are backed by the new InfluxDB IOx storage engine which enables nearly unlimited series cardinality and SQL query support. Check the right column of your InfluxDB Cloud organization homepage to see which InfluxDB storage engine you’re using.

If powered by TSM, this is the correct documentation.

If powered by IOx, see the IOx-based InfluxDB Cloud documentation.

State of the InfluxDB Cloud (IOx) documentation

The new documentation for InfluxDB Cloud backed by InfluxDB IOx is a work in progress. We are adding new information and content almost daily. Thank you for your patience!

If there is specific information you’re looking for, please submit a documentation issue.