InfluxDB Data Source

Query time series data from InfluxDB using Flux, InfluxQL, or SQL

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

For InfluxDB 1.x

SQL-like query language for InfluxDB 1.x:

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

Flux

For InfluxDB 2.x and 1.8+

Functional scripting language:

• Pipeline-based query construction
• Advanced data transformations
• Bucket-based organization

SQL

For InfluxDB 3.x

Native SQL support:

• Standard SQL syntax
• Better performance on InfluxDB 3.0+
• Familiar to SQL users

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

Connection Settings

1. Add Data Source

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

2. Select Query Language

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

3. 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
   
4. 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
5. 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)

1. Select Measurement

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

2. Add Tag Filters

   Filter by tag values:

   • Tag: host
   • Operator: =
   • Value: server-01
3. Select Fields

   Choose fields to query:

   • usage_idle
   • usage_system
4. Add Aggregation

   Select aggregation function:

   • mean()
   • max()
   • sum()
5. 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

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

Further Reading

• InfluxDB Official Documentation
• InfluxQL Reference
• Flux Language Guide
• InfluxDB 3.0 SQL Reference