Using SQL with InfluxDB 3

InfluxDB 3 Core supports native SQL for querying time series data. Its SQL implementation uses Apache Arrow DataFusion, so you can filter measurements by time, aggregate values, compare rows, and build queries for dashboards and applications. InfluxDB 3 Core also supports InfluxQL, a separate SQL-like query language. This guide focuses on SQL and the interfaces documented for InfluxDB 3 Core.

How does SQL work in InfluxDB 3?

InfluxDB 3 stores time series observations in tables. A measurement becomes a table; timestamps, tags, and fields appear as columns in SQL results. For example, a home table might have time, room, and temp columns. The SQL reference describes the DataFusion syntax, functions, quoting rules, and supported statements.

Use SELECT to choose columns, WHERE to filter by time or values, and GROUP BY to summarize readings. InfluxDB 3 Core can also run window functions, parameterized queries, and time-series functions such as date_bin and date_bin_gapfill. The SQL query guide has examples of each pattern.

InfluxDB 3 Core SQL support at a glance

These details are documented in the query interfaces, write guide, Grafana guide, and Core query guide.

Run a basic SQL query

The following example returns recent temperature readings from the documentation’s home sample table. Replace the database and column names with your own schema.

SELECT time, room, temp
FROM home
WHERE time >= now() - INTERVAL '1 day'
ORDER BY time DESC
LIMIT 10;

Run it with the CLI:

influxdb3 query --database DATABASE_NAME "SELECT time, room, temp FROM home WHERE time >= now() - INTERVAL '1 day' ORDER BY time DESC LIMIT 10"

Or send the query to the v3 HTTP API:

curl --get "http://localhost:8181/api/v3/query_sql" \
  --header "Authorization: Bearer AUTH_TOKEN" \
  --data-urlencode "db=DATABASE_NAME" \
  --data-urlencode "q=SELECT time, room, temp FROM home LIMIT 10"

The HTTP endpoint accepts GET or POST requests. It supports JSON, JSONL, CSV, Parquet, and human-readable output formats. Use named query parameters for values supplied by an application.

Aggregate readings into time intervals

Time series questions often ask for an average per hour rather than every raw point. date_bin assigns timestamps to fixed intervals, and an aggregate such as avg summarizes each group:

SELECT date_bin(INTERVAL '1 hour', time) AS time,
       room,
       avg(temp) AS avg_temp
FROM home
WHERE time >= now() - INTERVAL '1 day'
GROUP BY 1, room
ORDER BY 1, room;

If the result must include intervals with no readings, use date_bin_gapfill with interpolate or locf. See the gap-filling guide for the required grouping and time-bound syntax.

Connect SQL tools and plan around Core limits

InfluxDB 3 client libraries and Flight SQL clients can query InfluxDB 3 Core and retrieve Arrow data. Grafana’s InfluxDB data source also supports SQL through Flight SQL. Its SQL connection uses gRPC over HTTP/2, so a proxy or load balancer on that path must support HTTP/2. Include the time column when building a Grafana time series graph. See the Grafana setup guide.

SQL queries read data; they do not replace InfluxDB’s line protocol write path. For transformations or automated actions when data arrives, InfluxDB 3 Core provides Processing Engine Python plugins and triggers. Core is optimized for recent-data queries and limits each query to an approximately 72-hour time range. InfluxDB 3 Enterprise adds extended historical query capability.

Frequently asked questions