---
title: Operate on timestamps with Flux
description: Use Flux to operate on timestamps timestamps.
url: https://docs.influxdata.com/influxdb/cloud/query-data/flux/operate-on-timestamps/
estimated_tokens: 3800
product: InfluxDB Cloud (TSM)
version: cloud
---

# Operate on timestamps with Flux

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)

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/cloud/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/cloud/reference/glossary/#unix-timestamp) to an [RFC3339 timestamp](/influxdb/cloud/reference/glossary/#rfc3339-timestamp).

```js
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.

```js
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.

```js
time1 = uint(v: 2019-09-17T21:12:05Z)
time2 = uint(v: 2019-09-18T22:16:35Z)

duration(v: time2 - time1)
// Returns 25h4m30s

```

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()
```

`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()
```

`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.

```js
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.

```js
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/)
-   [experimental.addDuration() function](/flux/v0/stdlib/experimental/addduration/)
-   [experimental.subDuration() function](/flux/v0/stdlib/experimental/subduration/)