Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 39 ยท Querying: Flux and SQL

InfluxQL Basics: SQL-like Queries for InfluxDB

Learn InfluxQL, the SQL-like InfluxDB language: SELECT, WHERE with time and tags, GROUP BY time with fill, SHOW schema queries, limits and compatibility.

InfluxQL is the query language that started it all: it looks like SQL, it understands tags, fields and time, and it works in InfluxDB 1.x natively, in 2.x through a compatibility layer and in 3.x as one of the two supported languages. If you can read SQL, you can read InfluxQL in a few minutes, which makes it a good first language and a common choice for Grafana panels.

InfluxQL needs a server, so the statements below are read-only. Each is followed by a runnable SQLite or JavaScript stand-in that produces the equivalent result, so you can check your understanding of what the statement means.

Basic SELECT

TEXT
SELECT "usage_user", "usage_system" FROM "cpu"
WHERE time >= now() - 1h AND "host" = 'web-01'
ORDER BY time DESC
LIMIT 10

Differences from SQL that trip up newcomers:

  • Identifiers (measurement, tag and field names) go in double quotes when they contain special characters; they are optional for simple names but a good habit.
  • String values, including tag values, go in single quotes.
  • A query reads from the FROM measurement; to select from several, list them: FROM "cpu", "mem".
  • time is always available and is the default sort key (ascending).
  • now() is the current time, and durations are written with units: 5m, 1h, 7d, 30s, 1w (also u and ns).
  • Writing SELECT * returns all fields and tags; SELECT *::field returns only fields and SELECT *::tag only tags.
  • No joins. InfluxQL can query several measurements but cannot join them (use subqueries or process in the application; the SQL engine of 3.x has joins).
TEXT
SELECT "usage_user" FROM "cpu"
WHERE time >= '2026-03-01T00:00:00Z' AND time < '2026-03-02T00:00:00Z'
  AND "host" =~ /^web-/ AND "usage_user" > 80

A regular expression between slashes with =~ matches tags and measurements; !~ negates.

Aggregates and GROUP BY time

TEXT
SELECT mean("usage_user") AS "avg_user", max("usage_user") AS "peak"
FROM "cpu"
WHERE time >= now() - 6h AND "host" = 'web-01'
GROUP BY time(30m) fill(none)

GROUP BY time(30m) creates 30-minute windows aligned to the epoch (not to the query start). Add tags to group per series: GROUP BY time(30m), "host".

The fill() clause says what to do with empty windows:

fill Result for an empty window
fill(null) A row with a null value (default)
fill(none) No row at all
fill(0) A zero (or any literal)
fill(previous) The last known value
fill(linear) A straight line between neighbours

Common aggregates: count, sum, mean, median, min, max, first, last, spread, stddev, percentile(field, 95), mode, distinct. Selectors such as first, last, min, max return the timestamp of the selected point; true aggregates (mean, sum) return the window start (or epoch zero for ungrouped queries).

Filling windows: see it in code

The behaviour of fill is easiest to understand by watching it. This stand-in groups points into 10-minute windows and fills gaps in four ways. It is plain JavaScript.

JS What fill() does to empty windows (stand-in)

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

No output.

The same query in SQLite

Using SQL's GROUP BY on a computed bucket is the closest equivalent to GROUP BY time(). Missing windows simply do not appear, which matches fill(none); Windows, Gaps and Pivot shows how to bring them back.

SQL GROUP BY time(10m) in SQLite (stand-in)

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

Exploring the schema with SHOW

InfluxQL has statements that list what is in the database, great when you inherit an unknown system:

TEXT
SHOW MEASUREMENTS
SHOW FIELD KEYS FROM "cpu"
SHOW TAG KEYS FROM "cpu"
SHOW TAG VALUES FROM "cpu" WITH KEY = "host"
SHOW SERIES CARDINALITY
SHOW RETENTION POLICIES ON "mydb"

Use SHOW TAG VALUES ... WITH KEY to populate dashboard drop-downs. In InfluxDB 3 SHOW statements for measurements, tag keys and tag values are available, while some 1.x administrative statements are not.

Subqueries, INTO and limits

TEXT
-- mean of per-minute maxima (a subquery)
SELECT mean("peak") FROM (
  SELECT max("usage_user") AS "peak" FROM "cpu" WHERE time >= now() - 1h GROUP BY time(1m)
)

-- downsample into another measurement (1.x continuous-query style)
SELECT mean("usage_user") AS "usage_user" INTO "cpu_5m" FROM "cpu" GROUP BY time(5m), *

-- limit points per series and series per query
SELECT "usage_user" FROM "cpu" LIMIT 5 SLIMIT 2

LIMIT limits points per series; SLIMIT limits the number of series; OFFSET and SOFFSET skip. INTO writes results back, which is how 1.x continuous queries downsample (retention and downsampling are covered in the next chapter).

Using InfluxQL on other generations

  • 2.x: create a DBRP mapping that links a database and retention policy name to a bucket, then query the /query endpoint (or point Grafana's InfluxQL data source at it).
  • 3.x: select the InfluxQL language when querying (influxdb3 query --language influxql or the /query v1-compatible endpoint). Most SELECT features work; subqueries and some functions differ.

Common mistakes

Mistake Fix
Double quotes around a tag value Use single quotes: "host" = 'web-01'
Forgot a time lower bound Always add time >= ...; otherwise it reads everything
Selecting a field and a tag aggregate together Mix only with GROUP BY on that tag
GROUP BY time(1h) with no aggregate Windows need an aggregate function
Expecting joins Use subqueries or SQL on 3.x

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How should a tag value be quoted in InfluxQL?

    String and tag values use single quotes; double quotes are for identifiers.
  2. 2. What does fill(previous) do?

    fill(previous) carries the last non-empty value forward.
  3. 3. Which statement lists the values of the host tag?

    SHOW TAG VALUES WITH KEY returns the distinct values of one tag key.
  4. 4. Which InfluxDB generation needs a DBRP mapping to bridge databases to buckets for InfluxQL?

    InfluxQL is native in 1.x and 3.x; 2.x needs a DBRP mapping to bridge databases and retention policies to buckets.

Summary

  • InfluxQL is SQL-like: SELECT, WHERE, GROUP BY time(), plus tags, fields and now().
  • Single quotes for values, double quotes for identifiers; always bound the time range.
  • GROUP BY time(...) with fill() controls empty windows; SHOW statements explore the schema.
  • It has no joins; it works natively in 1.x, through DBRP mappings in 2.x and as a supported language in 3.x.

Next: SQL Time-series Queries