Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 39 ยท Querying: Flux and SQL

Flux: Filtering, Ranges and Aggregates

Write efficient Flux queries: time ranges, predicate pushdown, filtering by tag and field, last and max per series, derivative for counters, map and sort.

Once the pipeline idea from Flux Basics is clear, the next skill is writing queries that are both correct and cheap. A Flux query that scans a month of data to show the last value of one host will work but waste seconds on every dashboard refresh. This lesson covers time ranges, the order of filters, common selectors and aggregates, rates for counters and column calculations with map.

All Flux scripts here are read-only (they need an InfluxDB 2.x server). The runnable blocks are SQLite and JavaScript stand-ins that compute the same results from the same kind of data, so you can check what each Flux function should return.

Time ranges

range accepts relative and absolute times:

TEXT
|> range(start: -15m)                                   // last 15 minutes, stop = now()
|> range(start: -7d, stop: -1d)                          // a week ago to a day ago
|> range(start: 2026-03-01T00:00:00Z, stop: 2026-03-02T00:00:00Z)   // RFC 3339, no quotes
|> range(start: v.timeRangeStart, stop: v.timeRangeStop) // dashboard time picker

RFC 3339 timestamps are written without quotes in Flux: they are a literal type. The range is half-open: start is included, stop is excluded. Make the range as small as you need: it decides how much data the engine reads.

Filter early, filter on indexed columns

The Flux engine can push range and simple filter predicates down to storage, but only when they come right after from() and use _measurement, _field and tag columns. Put them first:

TEXT
// Good: predicates pushed down to storage
from(bucket: "metrics")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_user" and r.host == "web-01")
  |> aggregateWindow(every: 5m, fn: mean)

// Poor: reading everything first, then filtering on a computed value
from(bucket: "metrics")
  |> range(start: -1h)
  |> map(fn: (r) => ({ r with host_upper: strings.toUpper(v: r.host) }))
  |> filter(fn: (r) => r.host_upper == "WEB-01")

Rules of thumb: range first, then _measurement / _field / tag filters, and only then map, pivot, group, join and other heavy work. Filtering on _value is allowed and fine, but it cannot be pushed down the same way (values are not indexed).

Combine conditions with and, or, not; use contains for lists:

TEXT
|> filter(fn: (r) => contains(value: r.host, set: ["web-01", "web-02"]))
|> filter(fn: (r) => r._value > 80.0 and r.region != "test")

Selectors and aggregates

An aggregate returns one row per table, computed from many (mean, sum, count, median, stddev, spread). A selector returns an actual row of the input (first, last, min, max, top, bottom, limit), so the original timestamp survives.

Question Flux
Latest value per host `
Peak in the range and when it happened `
Top 3 loaded hosts `
Average per host `
Count of events `
95th percentile `
Newest 10 rows `

last() over a short range such as -10m is the standard way to show the current status. If a source reports rarely, widen the range: range(start: -1d) |> last() still reads only recent chunks, thanks to the time index.

TEXT
// Current CPU for every host
from(bucket: "metrics")
  |> range(start: -10m)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_user")
  |> last()

Stand-in: last, max and top in SQL

Here is the same data in SQLite and the answers to those questions. This is a stand-in for the Flux functions listed above.

SQL last, max and top per host (SQLite stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Counters: derivative and difference

Counters such as bytes sent or requests served only grow; you want their rate. In Flux:

TEXT
from(bucket: "metrics")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "net" and r._field == "bytes_sent")
  |> derivative(unit: 1s, nonNegative: true)   // bytes per second, resets count as zero
  |> aggregateWindow(every: 1m, fn: mean)

derivative computes change per unit of time between consecutive points; nonNegative: true treats a drop (counter reset) as a restart instead of a negative spike. difference() gives the plain difference of consecutive values without dividing by time. Apply derivative before aggregating into windows, otherwise averaging a counter first hides the rate.

JS derivative with nonNegative (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Real Flux drops the negative interval the same way when nonNegative is true (the row after a reset is skipped), which is why you may see a missing point right after a restart.

Computing columns with map

map rewrites each row. Use with to keep existing columns and add or replace others:

TEXT
|> map(fn: (r) => ({ r with _value: r._value * 1.8 + 32.0 }))     // Celsius to Fahrenheit
|> map(fn: (r) => ({ r with level: if r._value > 90.0 then "critical" else if r._value > 70.0 then "warn" else "ok" }))

if ... then ... else is an expression in Flux. For string work import strings; for math import math.

JS map with a computed level (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Combining queries: yield and multiple results

A script may produce several named results:

TEXT
data = from(bucket: "metrics") |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_user")

data |> mean() |> yield(name: "mean")
data |> max()  |> yield(name: "max")

Assigning the base stream to a variable avoids repeating the filter; both branches share the same source expression.

Performance checklist

  1. Smallest possible range.
  2. _measurement, _field and tag filters immediately after range.
  3. Select fewer series: avoid wildcards and broad regexes.
  4. Aggregate in the database (aggregateWindow) rather than pulling raw points to the client.
  5. Do pivot and join after reducing data.
  6. Use the Flux profiler (import "profiler", option profiler.enabledProfilers = ["query", "operator"]) when a query is slow.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which order lets InfluxDB push predicates down to storage?

    Predicates directly after from() on measurement, field and tag columns are pushed down.
  2. 2. What is the difference between an aggregate and a selector?

    last() returns a real row with its timestamp; mean() produces a computed value.
  3. 3. Why use nonNegative: true with derivative?

    After a restart the counter falls; nonNegative skips that interval.
  4. 4. How are RFC 3339 timestamps written in range()?

    Flux has a datetime literal type, so 2026-03-01T00:00:00Z needs no quotes.

Summary

  • Always keep range as small as possible and place measurement, field and tag filters right after it.
  • Aggregates reduce a table to a computed row; selectors such as last() and max() keep a real row.
  • Use derivative(nonNegative: true) before windowing counters and map for computed columns.
  • Name results with yield and reuse a base stream through a variable.

Next: InfluxQL Basics