Work with durations

A duration type represents a length of time with nanosecond precision.

Type name: duration

Duration syntax

Duration literals contain integers and unit specifiers. Flux supports the following unit specifiers:

  • ns: nanosecond
  • us: microsecond
  • ms: millisecond
  • s: second
  • m: minute
  • h: hour
  • d: day
  • w: week
  • mo: calendar month
  • y: calendar year
1ns // 1 nanosecond
1us // 1 microsecond
1ms // 1 millisecond
1s  // 1 second
1m  // 1 minute
1h  // 1 hour
1d  // 1 day
1w  // 1 week
1mo // 1 calendar month
1y  // 1 calendar year

3d12h4m25s // 3 days, 12 hours, 4 minutes, and 25 seconds

Do not include leading zeros in duration literals

The integer part of a duration literal should not contain leading zeros. Leading zeros are parsed as separate integer literals. For example:

01m // parsed as 0 (integer literal) and 1m (duration literal)
02h05m // parsed as 0 (integer literal), 2h (duration literal), 0 (integer literal), and 5m (duration literal)

Convert data types to durations

Use the duration() function to convert the following basic types to durations:

  • string: parsed as a duration string and converted to a duration.
  • int: parsed as nanoseconds and converted to a duration.
  • uint: parsed as nanoseconds and converted to a duration.
duration(v: "1h30m")
// Returns 1h30m

duration(v: 1000000)
// Returns 1ms

duration(v: uint(v: 3000000000))
// Returns 3s

Flux does not support duration columns.

Operate on durations

Perform arithmetic operations on durations

To perform operations like adding, subtracting, multiplying, or dividing duration values:

  1. Use int() or uint() to convert duration values to numeric values.
  2. Use arithmetic operators to operate on numeric values.
  3. Use duration() to convert the calculated numeric value into a duration.
duration(v: int(v: 6h4m) + int(v: 22h32s))
// Returns 1d4h4m32s

duration(v: int(v: 22h32s) - int(v: 6h4m))
// Returns 15h56m32s

duration(v: int(v: 32m10s) * 10)
// Returns 5h21m40s

duration(v: int(v: 24h) / 2)
// Returns 12h

Add a duration to a time value

  1. Import the experimental package.
  2. Use experimental.addDuration() to add a duration to a time value.
import "experimental"

experimental.addDuration(d: 1w, to: 2021-01-01T00:00:00Z)
// Returns 2021-01-08T00:00:00.000000000Z

Subtract a duration from a time value

  1. Import the experimental package.
  2. Use experimental.subDuration() to subtract a duration from a time value.
import "experimental"

experimental.subDuration(d: 1w, from: 2021-01-01T00:00:00Z)
// Returns 2020-12-25T00:00:00.000000000Z

Upgrade to InfluxDB Cloud or InfluxDB 2.0!

InfluxDB Cloud and InfluxDB OSS 2.0 ready for production.