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!


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.

Flux is going into maintenance mode and will not be supported in InfluxDB 3.0. This was a decision based on the broad demand for SQL and the continued growth and adoption of InfluxQL. We are continuing to support Flux for users in 1.x and 2.x so you can continue using it with no changes to your code. If you are interested in transitioning to InfluxDB 3.0 and want to future-proof your code, we suggest using InfluxQL.

For information about the future of Flux, see the following: