Work with time types

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

Type name: time

• Time syntax
• Convert data types to time
• Operate on 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:

• string: parsed as an RFC3339 timestamp and converted to a time value.
• int: parsed as a Unix nanosecond timestamp and converted to a time value.
• uint: parsed as a Unix nanosecond timestamp and converted to a time value.

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.

data
    |> toTime()

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) }))

Operate on time

• Truncate timestamps to a specified unit
• Parse units of time from a timestamp
• Add a duration to a time value
• Subtract a duration from a time value

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.

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)

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