--- title: Operate on timestamps with Flux description: Use Flux to process and operate on timestamps. url: https://docs.influxdata.com/influxdb/v2/query-data/flux/operate-on-timestamps/ estimated_tokens: 1712 product: InfluxDB OSS v2 version: v2 publisher: InfluxData canonical: https://docs.influxdata.com/influxdb/v2/query-data/flux/operate-on-timestamps/ date: '2025-04-02T15:54:32-06:00' lastmod: '2025-04-02T15:54:32-06:00' --- This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version. #### API token hashing is enabled by default in InfluxDB OSS 2.9.0 Stronger token security: tokens are stored as hashes on disk, so a copy of the database file doesn’t expose usable tokens. Existing tokens are hashed on first startup and the original strings can’t be recovered afterward — **capture any plaintext tokens you still need before you upgrade**. For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing). Every point stored in InfluxDB has an associated timestamp. Use Flux to process and operate on timestamps to suit your needs. * [Convert timestamp format](#convert-timestamp-format) * [Calculate the duration between two timestamps](#calculate-the-duration-between-two-timestamps) * [Retrieve the current time](#retrieve-the-current-time) * [Normalize irregular timestamps](#normalize-irregular-timestamps) * [Use timestamps and durations together](#use-timestamps-and-durations-together) > [!Note] > If you’re just getting started with Flux queries, check out the following: > * [Get started with Flux](/flux/v0/get-started/) for a conceptual overview of Flux and parts of a Flux query. > * [Execute queries](/influxdb/v2/query-data/execute-queries/) to discover a variety of ways to run your queries. * [Get started with Flux](/flux/v0/get-started/) for a conceptual overview of Flux and parts of a Flux query. * [Execute queries](/influxdb/v2/query-data/execute-queries/) to discover a variety of ways to run your queries. ## Convert timestamp format * [Unix nanosecond to RFC3339](#unix-nanosecond-to-rfc3339) * [RFC3339 to Unix nanosecond](#rfc3339-to-unix-nanosecond) ### Unix nanosecond to RFC3339 Use the [`time()` function](/flux/v0/stdlib/universe/time/)to convert a [Unix **nanosecond** timestamp](/influxdb/v2/reference/glossary/#unix-timestamp)to an [RFC3339 timestamp](/influxdb/v2/reference/glossary/#rfc3339-timestamp). ``` time(v: 1568808000000000000) // Returns 2019-09-18T12:00:00.000000000Z ``` ### RFC3339 to Unix nanosecond Use the [`uint()` function](/flux/v0/stdlib/universe/uint/)to convert an RFC3339 timestamp to a Unix nanosecond timestamp. ``` uint(v: 2019-09-18T12:00:00.000000000Z) // Returns 1568808000000000000 ``` ## Calculate the duration between two timestamps Flux doesn’t support mathematical operations using [time type](/flux/v0/spec/types/#time-types) values. To calculate the duration between two timestamps: 1. Use the `uint()` function to convert each timestamp to a Unix nanosecond timestamp. 2. Subtract one Unix nanosecond timestamp from the other. 3. Use the `duration()` function to convert the result into a duration. ``` time1 = uint(v: 2019-09-17T21:12:05Z) time2 = uint(v: 2019-09-18T22:16:35Z) duration(v: time2 - time1) // Returns 25h4m30s ``` > [!Note] > Flux doesn’t support duration column types. > To store a duration in a column, use the [`string()` function](/flux/v0/stdlib/universe/string/)to convert the duration to a string. ## Retrieve the current time * [Current UTC time](#current-utc-time) * [Current system time](#current-system-time) ### Current UTC time Use the [`now()` function](/flux/v0/stdlib/universe/now/) to return the current UTC time in RFC3339 format. ```js now() ``` > [!Note] > `now()` is cached at runtime, so all instances of `now()` in a Flux script > return the same value. ### Current system time Import the `system` package and use the [`system.time()` function](/flux/v0/stdlib/system/time/)to return the current system time of the host machine in RFC3339 format. ```js import "system" system.time() ``` > [!Note] > `system.time()` returns the time it is executed, so each instance of `system.time()`in a Flux script returns a unique value. ## Normalize irregular timestamps To normalize irregular timestamps, truncate all `_time` values to a specified unit with the [`truncateTimeColumn()` function](/flux/v0/stdlib/universe/truncatetimecolumn/). This is useful in [`join()`](/flux/v0/stdlib/universe/join/)and [`pivot()`](/flux/v0/stdlib/universe/pivot/)operations where points should align by time, but timestamps vary slightly. ```js data |> truncateTimeColumn(unit: 1m) ``` **Input:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:49Z| 2.0 | |2020-01-01T00:01:01Z| 1.9 | |2020-01-01T00:03:22Z| 1.8 | |2020-01-01T00:04:04Z| 1.9 | |2020-01-01T00:05:38Z| 2.1 | **Output:** | \_time |\_value| |--------------------|-------| |2020-01-01T00:00:00Z| 2.0 | |2020-01-01T00:01:00Z| 1.9 | |2020-01-01T00:03:00Z| 1.8 | |2020-01-01T00:04:00Z| 1.9 | |2020-01-01T00:05:00Z| 2.1 | ## Use timestamps and durations together * [Add a duration to a timestamp](#add-a-duration-to-a-timestamp) * [Subtract a duration from a timestamp](#subtract-a-duration-from-a-timestamp) ### Add a duration to a timestamp [`date.add()`](/flux/v0/stdlib/date/add/)adds a duration to a specified time and returns the resulting time. ``` import "date" date.add(d: 6h, to: 2019-09-16T12:00:00Z) // Returns 2019-09-16T18:00:00.000000000Z ``` ### Subtract a duration from a timestamp [`date.sub()`](/flux/v0/stdlib/date/sub/)subtracts a duration from a specified time and returns the resulting time. ``` import "date" date.sub(d: 6h, from: 2019-09-16T12:00:00Z) // Returns 2019-09-16T06:00:00.000000000Z ``` ### Shift a timestamp forward or backward The [timeShift()](/flux/v0/stdlib/universe/timeshift/) function adds the specified duration of time to each value in time columns (`_start`, `_stop`, `_time`). Shift forward in time: ```js from(bucket: "example-bucket") |> range(start: -5m) |> timeShift(duration: 12h) ``` Shift backward in time: ```js from(bucket: "example-bucket") |> range(start: -5m) |> timeShift(duration: -12h) ``` #### Related * [now() function](/flux/v0/stdlib/universe/now/) * [system.time() function](/flux/v0/stdlib/system/time/) * [time() function](/flux/v0/stdlib/universe/time/) * [uint() function](/flux/v0/stdlib/universe/uint/) * [int() function](/flux/v0/stdlib/universe/int/) * [truncateTimeColumn() function](/flux/v0/stdlib/universe/truncatetimecolumn/) * [date.truncate() function](/flux/v0/stdlib/date/truncate/) * [date.add() function](/flux/v0/stdlib/date/add/) * [date.sub() function](/flux/v0/stdlib/date/sub/) | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:49Z | 2.0 | | 2020-01-01T00:01:01Z | 1.9 | | 2020-01-01T00:03:22Z | 1.8 | | 2020-01-01T00:04:04Z | 1.9 | | 2020-01-01T00:05:38Z | 2.1 | | _time | _value | | --- | --- | | _time | _value | | 2020-01-01T00:00:00Z | 2.0 | | 2020-01-01T00:01:00Z | 1.9 | | 2020-01-01T00:03:00Z | 1.8 | | 2020-01-01T00:04:00Z | 1.9 | | 2020-01-01T00:05:00Z | 2.1 |