Documentation Grafana documentation Data sources InfluxDB Query editor

InfluxDB query editor

The InfluxDB query editor helps you build and run queries against your InfluxDB data source. You can access it from the Explore page or from any dashboard panel by clicking the ellipsis in the upper right of the panel and selecting Edit.

The editor supports three query languages — SQL, InfluxQL, and Flux — each with its own editing experience and macro system. SQL and InfluxQL provide both a visual builder mode and a code editing mode, while Flux provides a code editor only. You can also use the query editor to retrieve log data.

For general information about Grafana query editors, refer to Query and transform data.

Before you begin

• Ensure you have configured the InfluxDB data source.
• Verify your credentials have appropriate permissions to query the target database or bucket.

Key concepts

If you’re new to InfluxDB, these terms are used throughout the query editor:

Choose a query editor

The InfluxDB data source has three query editors, each corresponding to the query language selected in the data source configuration:

• InfluxQL
• SQL
• Flux

Editor options vary based on query language.

InfluxQL query editor

The InfluxQL query editor helps you select metrics and tags to create InfluxQL queries. There are two modes: visual editor mode and raw query mode. To switch between the two modes click the pencil icon in the upper right.

Visual query editor mode contains the following components:

• FROM - Select a measurement to query.
• WHERE - Select filters by clicking the + sign. You can enter regular expressions or use the text input for regular expression tag values.
• SELECT - Select fields and functions from the drop-down. You can add multiple fields and functions by clicking the + sign.
• GROUP BY - Select a tag from the drop-down menu.
• TIMEZONE - Optional Group data by a specific timezone.
• ORDER BY TIME - Sort data by time in either ascending or descending order.
• LIMIT - Optional Limits the number of rows returned by the query.
• SLIMIT - Optional Limits the number of series returned by the query. Refer to SLIMIT clause for more information.
• FORMAT AS - Select a format option from the drop-down menu: time series, table, or logs.
• ALIAS - Add an alias. Refer to Alias patterns for more information.

Raw query editor mode

You can write raw InfluxQL queries by switching to raw query mode. Click the pencil in the upper right of the query editor to switch modes. When you switch to visual editor mode, any changes made in raw query mode are lost.

If you use raw query mode, your query must include WHERE $timeFilter. You should also provide a group by time and an aggregation function. Otherwise, InfluxDB may return hundreds of thousands of data points, potentially causing your browser to hang.

Match by regular expressions

You can enter regular expressions for metric names or tag filter values. Wrap the regular expression pattern in forward slashes (/), as shown in this example: /measurement/.

Grafana automatically adjusts the filter tag condition to use the InfluxDB regular expression match condition operator (=~).

Field and aggregation functions

In the SELECT row, you can specify which fields and functions to use.

If you group by time you must use an aggregation function. Certain functions such as derivative also require an aggregation function.

The query editor input generates an InfluxDB SELECT clause. For example:

SQL Copy

SELECT derivative(mean("value"), 10s) / 10 AS "REQ/s"
FROM....

You can also use a * in a SELECT statement to select all fields.

SQL Copy

SELECT * FROM <measurement_name>

GROUP BY results

To group results by a tag, specify the tag in the GROUP BY row:

1. Click the + sign in the GROUP BY row.
2. Select a tag from the drop-down.

You can GROUP BY multiple options.

To remove a GROUP BY option click the X icon next to the option.

Alias patterns

You can also use the [[tag_hostname]] pattern replacement syntax.

For example, entering the value Host: [[tag_hostname]] in the ALIAS BY field replaces it with the hostname tag value for each legend value.

An example legend value is Host: server1.

SQL query editor

Grafana supports the SQL query language for InfluxDB 3.x and newer cloud products (Cloud Serverless, Cloud Dedicated, Clustered). SQL is InfluxData’s recommended query language for new deployments.

The SQL query editor provides two modes:

• Builder mode - A visual query builder that helps you construct SQL queries by selecting tables, columns, filters, and aggregations from drop-down menus. This mode is useful for building queries without writing SQL directly.
• Code mode - A text editor for writing raw SQL queries with autocomplete and syntax highlighting. Switch between modes using the toggle at the top of the query editor.

SQL queries connect to InfluxDB using the FlightSQL (gRPC) protocol, which provides high-performance data transfer for large result sets.

Format output

The SQL query editor supports two output formats:

• Time series (default) - Returns data as time-series frames. The query must include a timestamp column.
• Table - Returns data as a table frame, useful for non-time-series queries or when you want to display raw results.

Select the format from the Format drop-down in the query editor.

Macros

You can use macros in your query to automatically substitute them with values from the Grafana context.

SQL query examples

Basic time-series query:

SQL Copy

SELECT time, usage_system, usage_user
FROM cpu
WHERE $__timeFilter(time)
ORDER BY time

Aggregated time-series query with date_bin:

SQL Copy

SELECT
  $__dateBin(time) AS time,
  mean(usage_system) AS avg_system,
  mean(usage_user) AS avg_user
FROM cpu
WHERE $__timeFilter(time)
GROUP BY $__dateBin(time)
ORDER BY time

Using JOINs across tables:

SQL supports JOINs, which aren’t available in InfluxQL or Flux:

SQL Copy

SELECT
  c.time,
  c.usage_system,
  m.used_percent AS mem_used
FROM cpu c
INNER JOIN mem m ON c.time = m.time AND c.host = m.host
WHERE $__timeFilter(c.time)
ORDER BY c.time

Filtering with WHERE clauses:

SQL Copy

SELECT $__dateBin(time) AS time, mean(usage_system) AS avg_system
FROM cpu
WHERE $__timeFilter(time)
  AND host = 'server01'
  AND cpu = 'cpu-total'
GROUP BY $__dateBin(time)
ORDER BY time

For the full list of supported SQL statements, operators, and functions, refer to InfluxData’s SQL reference documentation.

Flux query editor

Grafana supports Flux when running InfluxDB v1.8 and higher. If your data source is configured for Flux, you can use the Flux in the query editor, which serves as a text editor for raw Flux queries with macro support.

For more information and connection details, refer to InfluxDB 1.8 API compatibility.

Use macros

You can enter macros in the query to replace them with values from the Grafana context.

Macros support copying and pasting from InfluxData Chronograf.

For example, consider the following Flux query:

flux Copy

from(bucket: v.defaultBucket)
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r["_measurement"] == "cpu" or r["_measurement"] == "swap")
  |> filter(fn: (r) => r["_field"] == "usage_system" or r["_field"] == "free")
  |> aggregateWindow(every: v.windowPeriod, fn: mean)
  |> yield(name: "mean")

Grafana interpolates this Flux query into the following and sends it to InfluxDB, with the interval and time period values changing according to the active time selection:

flux Copy

from(bucket: "grafana")
  |> range(start: 2020-06-11T13:59:07Z, stop: 2020-06-11T14:59:07Z)
  |> filter(fn: (r) => r["_measurement"] == "cpu" or r["_measurement"] == "swap")
  |> filter(fn: (r) => r["_field"] == "usage_system" or r["_field"] == "free")
  |> aggregateWindow(every: 2s, fn: mean)
  |> yield(name: "mean")

To view the interpolated version of a query with the Query inspector, refer to Panel Inspector.

Query logs

You can query and display log data from InfluxDB in Explore and in the dashboard Logs panel.

InfluxQL: Select an InfluxDB data source in the query editor. Under the Select measurement field next to the FROM section, choose a measurement containing your log data, then choose the appropriate fields that will display the log message. Add any additional filters by clicking the + sign next to the WHERE field. Set FORMAT AS to Logs.

SQL: Write a SQL query that returns a timestamp column and a text column containing the log message. Set the Format to Table. For example:

SQL Copy

SELECT time, message, level, host
FROM syslog
WHERE $__timeFilter(time)
ORDER BY time DESC

Flux: Use a Flux query with the _value field containing the log message.

After InfluxDB returns the results, the log panel displays log rows along with a bar chart. The x-axis represents time, while the y-axis shows the frequency or count.

Next steps

• Use template variables for dynamic dashboards.
• Set up annotations to overlay events on your graphs.
• Create alert rules based on your InfluxDB queries.