TL;DR Tech Tips — Flux Time Ranges

Nora Mullen (InfluxData) — Fri, 26 Jun 2020 07:00:35 -0700

In this post, we share some basics about working with time ranges in Flux.

Q: What's the role of time ranges in Flux queries?

A: Flux requires a time range when querying InfluxDB. “Unbounded” queries are very resource-intensive and as a protective measure, Flux won’t query InfluxDB without a specified range.

After you use the from() function to define a data source, use the pipe-forward operator (|>) to pipe data from your data source into the range() function. (We’ll dive into specific examples below.)

Q: What parameters does the range() function have?

A: The range() function has two parameters: start, the earliest time to include in results, and stop. For each parameter, define either a relative or absolute time. Learn more about each option below.

Q: How do you set a relative time range in Flux?

A: Define a relative range for your Flux query using durations relative to now(). Durations are formatted as duration literals, representations of a length of time with an integer part and a duration unit part: for example, -1h represents a time range of one hour before now.

Example relative time range in a Flux query

// Relative time range with start only. Stop defaults to now.
from(bucket:"example-bucket")
  |> range(start: -1h)
  // ...

// Relative time range with start and stop
from(bucket:"example-bucket")
  |> range(start: -1h, stop: -10m)
  // ...

Q: How do you set an absolute time range in Flux?

A: Define an absolute range for your Flux query using timestamps. Timestamps are formatted as date and time literals, composed of a date part, a time part, and an optional time offset par: for example, 2019-10-15T09:00:00 represents October 15, 2019.

Example absolute time range

from(bucket:"example-bucket")
  |> range(start: 2019-11-05T23:30:00Z, stop: 2019-11-06T00:00:00Z)
  // ...

Q: Does the `range()` function include points that match the start or stop time?

A: For the start parameter, results include points that match the specified start time. For the stop parameter, results exclude points that match the specified end time.

In the following example, points matching -12h would be included and points matching -15m would be excluded.

from(bucket:"example-bucket")
  |> range(start:-12h, stop: -15m)
  // ...

TL;DR InfluxDB Tech Tips – Flux Timestamps

Nora Mullen (InfluxData) — Thu, 11 Jun 2020 07:00:10 -0700

In this post, we share some quick examples of how you can work with timestamps in Flux.

Q: What timestamp formats are available in Flux?

A: There are two timestamp formats available:

Unix timestamp

A Unix timestamp counts time since Unix Epoch (1970-01-01T00:00:00Z UTC) in specified units. The units are determined by the precision you set when writing data to InfluxDB.

InfluxDB supports the following Unix timestamp precisions:

Precision	Description	Example
`ns`	Nanoseconds	`1577836800000000000`
`us`	Microseconds	`1577836800000000`
`ms`	Milliseconds	`1577836800000`
`s`	Seconds	`1577836800`

The examples above represent 2020-01-01T00:00:00Z UTC.

RFC3339 timestamp

An RFC3339 timestamp that uses the human readable DateTime format proposed in RFC 3339 (for example: 2020-01-01T00:00:00.00Z). Flux and InfluxDB clients return query results with RFC3339 timestamps.

Q: How do I convert the timestamp format?

A: To convert timestamps from Unix nanoseconds to a human readable RFC3339 timestamp, use the time() function.

time(v: 1568808000000000000)
// Returns 2019-09-18T12:00:00.000000000Z

To convert timestamps from RFC3339 to Unix nanoseconds, use the uint() function.

uint(v: 2019-09-18T12:00:00.000000000Z)
// Returns 1568808000000000000

Q: How do I calculate the duration between two timestamps?

A: Flux doesn’t support mathematical operations using time type values. To calculate the duration between two timestamps:

Use the uint() function to convert each timestamp to a Unix nanosecond timestamp.
Subtract one Unix nanosecond timestamp from the other.
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

Q: How do I retrieve the current time?

A: To retrieve the current time in UTC, use the now() function. Note that the now() function is cached at runtime, so all instances of now() return the same value.

now()

To retrieve the current system time of the host machine in RFC3339 format, import the system package and the system.time() function:

import "system"

system.time()

InfluxData Blog - Nora Mullen