--- title: Work with time types description: A time type represents a single point in time with nanosecond precision. Learn how to work with time data types in Flux. url: https://docs.influxdata.com/flux/v0/data-types/basic/time/ estimated_tokens: 4739 product: Flux version: v0 --- # Work with time types A **time** type represents a single point in time with nanosecond precision. **Type name**: `time` - [Time syntax](#time-syntax) - [Convert data types to time](#convert-data-types-to-time) - [Operate on time](#operate-on-time) ## Time syntax Time literals are represented by [RFC3339 timestamps](/influxdb/cloud/reference/glossary/#rfc3339-timestamp). ``` YYYY-MM-DD YYYY-MM-DDT00:00:00Z YYYY-MM-DDT00:00:00.000Z ``` ## Convert data types to time Use the [`time()` function](/flux/v0/stdlib/universe/time/) to convert the following [basic types](/flux/v0/data-types/basic/) to time: - **string**: parsed as an [RFC3339 timestamp](/influxdb/cloud/reference/glossary/#rfc3339-timestamp) and converted to a time value. - **int**: parsed as a [Unix nanosecond timestamp](/influxdb/cloud/reference/glossary/#unix-timestamp) and converted to a time value. - **uint**: parsed as a [Unix nanosecond timestamp](/influxdb/cloud/reference/glossary/#unix-timestamp) and converted to a time value. ```js 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](/flux/v0/get-started/data-model/#stream-of-tables) and convert columns to time. **To convert the `_value` column to time**, use the [`toTime()` function](/flux/v0/stdlib/universe/totime/). `toTime()` only operates on the `_value` column. ```js 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()`](/flux/v0/stdlib/universe/map/) to iterate over and rewrite rows. 2. Use [`time()`](/flux/v0/stdlib/universe/time/) to convert columns values to time. ```js 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](#truncate-timestamps-to-a-specified-unit) - [Parse units of time from a timestamp](#parse-units-of-time-from-a-timestamp) - [Add a duration to a time value](#add-a-duration-to-a-time-value) - [Subtract a duration from 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](/flux/v0/stdlib/date/). 2. Use [`date.truncate()`](/flux/v0/stdlib/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. ```js 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()`](/flux/v0/stdlib/universe/truncatetimecolumn/)**: ```js 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](/flux/v0/stdlib/date/). 2. Use functions in the `date` package to return specific units of time from a timestamp. ```js 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](/flux/v0/data-types/basic/duration/) to a time value: 1. Import the [`date` package](/flux/v0/stdlib/date/). 2. Use [`date.add()`](/flux/v0/stdlib/date/add/) to add a duration to a time value. ```js 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](/flux/v0/data-types/basic/duration/) from a time value: 1. Import the [`date` package](/flux/v0/stdlib/date/). 2. Use [`date.sub()`](/flux/v0/stdlib/date/sub/) to subtract a duration from a time value. ```js import "date" date.sub(d: 1w, from: 2021-01-01T00:00:00Z) // Returns 2020-12-25T00:00:00.000000000Z ``` #### Related - [time() function](/flux/v0/stdlib/universe/time/) - [toTime() function](/flux/v0/stdlib/universe/totime/) [basic types](/flux/v0/tags/basic-types/) [data types](/flux/v0/tags/data-types/) [date/time](/flux/v0/tags/date/time/)