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:
_timeepoch_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:
_timeepoch_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 experimental package.
  2. Use experimental.addDuration() to add a duration to a time value.
import "experimental"

experimental.addDuration(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 experimental package.
  2. Use experimental.subDuration() to subtract a duration from a time value.
import "experimental"

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

Upgrade to InfluxDB Cloud or InfluxDB 2.0!

InfluxDB Cloud and InfluxDB OSS 2.0 ready for production.