InfluxDB Data Source

InfluxDB is a time series database optimized for high-write and query loads. Grafana supports querying InfluxDB using three query languages: InfluxQL (1.x), Flux (2.x and 1.8+), and SQL (3.x).

Overview

The InfluxDB data source provides:

Support for InfluxQL, Flux, and SQL query languages
Time series visualization and aggregation
Retention policy and bucket management
Template variables from InfluxDB data
Annotation support

Source: public/app/plugins/datasource/influxdb/

Configuration

Query Language Selection

First, select your query language based on your InfluxDB version:

InfluxQL
Flux
SQL

For InfluxDB 1.xSQL-like query language for InfluxDB 1.x:

Familiar SQL-style syntax
Database and retention policy support
Continuous queries and retention policies

Source: public/app/plugins/datasource/influxdb/components/editor/config/ConfigEditor.tsx:21-43

Connection Settings

Add Data Source

Navigate to Configuration > Data Sources > Add data source > InfluxDB

Select Query Language

Choose InfluxQL, Flux, or SQL based on your InfluxDB version

Configure URL

Set the InfluxDB server URL:InfluxDB 1.x (InfluxQL):

http://localhost:8086

InfluxDB 2.x (Flux):

http://localhost:8086

InfluxDB 3.x (SQL):

https://your-instance.influxdata.com

Authentication

InfluxQL (1.x):

Enable Basic Auth
Set username and password

Flux (2.x) / SQL (3.x):

Set organization name
Provide API token in secure settings

Database/Bucket Settings

InfluxQL:

Database: telegraf
Retention Policy: autogen (optional)

Flux/SQL:

Default Bucket: my-bucket

Data Source Options

version

string

required

Query language: InfluxQL, Flux, or SQL

database

string

InfluxQL only: Database name

organization

string

Flux/SQL only: Organization name

defaultBucket

string

Flux/SQL only: Default bucket for queries

maxSeries

number

default:"1000"

Limit the number of series/tables processed. Prevents performance issues with high-cardinality data.

Source: public/app/plugins/datasource/influxdb/components/editor/config/ConfigEditor.tsx:141-158

InfluxQL Query Language

Basic Queries

Select data from a measurement:

SELECT "value" FROM "cpu" WHERE time >= now() - 1h

Aggregations

Mean:

SELECT mean("value") FROM "cpu" WHERE $timeFilter GROUP BY time($__interval)

Multiple aggregations:

SELECT 
  mean("value") AS "avg",
  max("value") AS "max",
  min("value") AS "min"
FROM "cpu"
WHERE $timeFilter
GROUP BY time($__interval)

Group By Tags

Group by tag values:

SELECT mean("value") 
FROM "cpu" 
WHERE $timeFilter 
GROUP BY time($__interval), "host"

Sub-queries

SELECT mean("max") FROM (
  SELECT max("value") FROM "cpu" 
  WHERE $timeFilter 
  GROUP BY time(1m), "host"
) GROUP BY time(5m)

Macros

Grafana provides InfluxQL macros:

$timeFilter: Expands to time >= <start> AND time <= <end>
$__interval: Auto-calculated time interval
$__interval_ms: Interval in milliseconds

Flux Query Language

Basic Queries

Query data from a bucket:

from(bucket: "telegraf")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu")
  |> filter(fn: (r) => r._field == "usage_idle")

Aggregations

Mean:

from(bucket: "telegraf")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r._measurement == "cpu")
  |> filter(fn: (r) => r._field == "usage_system")
  |> aggregateWindow(every: v.windowPeriod, fn: mean)

Custom aggregation:

from(bucket: "telegraf")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "mem")
  |> aggregateWindow(
      every: 1m,
      fn: (column, tables=<-) => tables |> mean(column: column)
    )

Group By

Group by tags:

from(bucket: "telegraf")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu")
  |> group(columns: ["host", "_field"])
  |> mean()

Transformations

Map:

from(bucket: "telegraf")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "temp")
  |> map(fn: (r) => ({ r with _value: (r._value * 9.0 / 5.0) + 32.0 }))

Join:

cpu = from(bucket: "telegraf")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu")

mem = from(bucket: "telegraf")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "mem")

join(
  tables: {cpu: cpu, mem: mem},
  on: ["_time", "host"]
)

Flux Variables

Grafana provides Flux variables:

v.timeRangeStart: Dashboard start time
v.timeRangeStop: Dashboard stop time
v.windowPeriod: Auto-calculated window period
v.defaultBucket: Configured default bucket

SQL Query Language (InfluxDB 3.x)

Basic Queries

Select from a measurement:

SELECT time, host, usage_idle
FROM cpu
WHERE time >= now() - INTERVAL '1 hour'
ORDER BY time

Aggregations

SELECT 
  DATE_BIN(INTERVAL '5 minutes', time) AS time_bucket,
  AVG(usage_system) AS avg_usage,
  MAX(usage_system) AS max_usage
FROM cpu
WHERE time >= now() - INTERVAL '1 hour'
GROUP BY time_bucket
ORDER BY time_bucket

Group By

SELECT 
  DATE_BIN(INTERVAL '1 minute', time) AS time_bucket,
  host,
  AVG(usage_idle) AS avg_idle
FROM cpu
WHERE time >= now() - INTERVAL '6 hours'
GROUP BY time_bucket, host
ORDER BY time_bucket

Window Functions

SELECT 
  time,
  host,
  usage_idle,
  AVG(usage_idle) OVER (
    PARTITION BY host 
    ORDER BY time 
    ROWS BETWEEN 5 PRECEDING AND CURRENT ROW
  ) AS moving_avg
FROM cpu
WHERE time >= now() - INTERVAL '1 hour'

Query Editor

Visual Query Builder (InfluxQL)

Select Measurement

Choose measurement from dropdown (e.g., cpu)

Add Tag Filters

Filter by tag values:

Tag: host
Operator: =
Value: server-01

Select Fields

Choose fields to query:

usage_idle
usage_system

Add Aggregation

Select aggregation function:

mean()
max()
sum()

Group By

Add grouping:

time($__interval)
Tag: host

Code Editor

Switch to code mode for advanced queries:

Full query language support
Syntax highlighting
Query validation
Variable substitution preview

Template Variables

InfluxQL Variables

Show tag values:

SHOW TAG VALUES WITH KEY = "host"

Show tag values with condition:

SHOW TAG VALUES FROM "cpu" WITH KEY = "host" WHERE region = '$region'

Show measurements:

SHOW MEASUREMENTS

Show field keys:

SHOW FIELD KEYS FROM "cpu"

Flux Variables

Get tag values:

import "influxdata/influxdb/v1"

v1.tagValues(
  bucket: "telegraf",
  tag: "host"
)

Get measurements:

import "influxdata/influxdb/schema"

schema.measurements(bucket: "telegraf")

SQL Variables (InfluxDB 3.x)

Get distinct values:

SELECT DISTINCT host FROM cpu

Get values with filter:

SELECT DISTINCT region FROM cpu WHERE datacenter = '$datacenter'

Using Variables in Queries

InfluxQL:

SELECT mean("value") FROM "cpu" WHERE "host" =~ /^$host$/ AND $timeFilter

Flux:

from(bucket: "$bucket")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r.host == "${host}")

SQL:

SELECT * FROM cpu WHERE host = '$host' AND time >= now() - INTERVAL '1 hour'

Performance Optimization

Use Retention Policies

Configure appropriate retention policies to reduce data volume:

SELECT mean("value") FROM "telegraf"."autogen"."cpu"

Limit Series

Set maxSeries to prevent high-cardinality issues:

maxSeries: 1000

Use Downsampling

Query pre-aggregated data from continuous queries:

SELECT mean FROM "cpu_mean_5m" WHERE $timeFilter

Add Tag Filters

Always filter by tags to reduce query scope:

|> filter(fn: (r) => r.host == "server-01")

Annotations

Create annotations from InfluxDB data: InfluxQL:

SELECT "message" FROM "events" WHERE $timeFilter

Flux:

from(bucket: "events")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r._measurement == "deployments")

Configure:

Text Column: Field containing annotation text
Tags Column: Field containing comma-separated tags

Troubleshooting

No data returned

Verify database/bucket name is correct
Check retention policy (InfluxQL) or bucket retention (Flux/SQL)
Confirm time range includes data points
Test query in InfluxDB CLI or UI
Review time field format and timezone

Authentication failed

InfluxQL: Verify username/password in Basic Auth
Flux/SQL: Check API token has correct permissions
Confirm organization name is correct (Flux/SQL)
Review InfluxDB user permissions

Query timeout

Reduce time range
Add more tag filters
Lower maxSeries setting
Use continuous queries for pre-aggregation
Increase query timeout in InfluxDB config

Too many series

Lower maxSeries in data source settings
Add tag filters to reduce cardinality
Use more specific measurement names
Review tag cardinality: SHOW TAG CARDINALITY

Best Practices

Choose the right query language: Use InfluxQL for 1.x, Flux for 2.x, SQL for 3.x
Use tag filters: Always filter by tags before field operations
Configure retention policies: Set appropriate data retention for your use case
**Avoid SELECT ***: Query only needed fields
Use continuous queries: Pre-aggregate data for common queries
Monitor cardinality: Keep tag cardinality low (< 100k series per measurement)
Leverage macros/variables: Use Grafana’s built-in time variables

Overview

Getting Started

Dashboards

Data Sources

Alerting

Explore

Visualization

​InfluxDB Data Source

​Overview

​Configuration

​Query Language Selection

​Connection Settings

​Data Source Options

​InfluxQL Query Language

​Basic Queries

​Aggregations

​Group By Tags

​Sub-queries

​Macros

​Flux Query Language

​Basic Queries

​Aggregations

​Group By

​Transformations

​Flux Variables

​SQL Query Language (InfluxDB 3.x)

​Basic Queries

​Aggregations

​Group By

​Window Functions

​Query Editor

​Visual Query Builder (InfluxQL)

​Code Editor

​Template Variables

​InfluxQL Variables

​Flux Variables

​SQL Variables (InfluxDB 3.x)

​Using Variables in Queries

​Performance Optimization

Use Retention Policies

Limit Series

Use Downsampling

Add Tag Filters

​Annotations

​Troubleshooting

​Best Practices

​Further Reading

InfluxDB Data Source

Overview

Configuration

Query Language Selection

Connection Settings

Data Source Options

InfluxQL Query Language

Basic Queries

Aggregations

Group By Tags

Sub-queries

Macros

Flux Query Language

Basic Queries

Aggregations

Group By

Transformations

Flux Variables

SQL Query Language (InfluxDB 3.x)

Basic Queries

Aggregations

Group By

Window Functions

Query Editor

Visual Query Builder (InfluxQL)

Code Editor

Template Variables

InfluxQL Variables

Flux Variables

SQL Variables (InfluxDB 3.x)

Using Variables in Queries

Performance Optimization

Annotations

Troubleshooting

Best Practices

Further Reading