TL;DR Tech Tips — Flux Time Ranges

By Nora Mullen / Product, Use Cases, Developer
Jun 26, 2020

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)
  // ...