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:
- 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.
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:
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
- 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:
- Import the
date
package. - 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:
- Import the
date
package. - 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:
- Import the
date
package. - 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:
- Import the
date
package. - 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!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for Flux and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.