InfluxQL Cheatsheet: Mastering Time-Series Data Querying

1. Connection and Basic Setup

InfluxDB CLI Connection

1
2
3
4
5
6
7
8
9
10
# InfluxDB 1.x CLI
influx -host localhost -port 8086 -username admin -password secret

# InfluxDB 2.x / 3.x: enable the v1 compatibility endpoint, then use `influx v1`
# (or query via the /query?db=... HTTP endpoint with a v1-auth token)
influx v1 shell --token <TOKEN>

# Select a database (1.x) or DBRP-mapped bucket (2.x/3.x)
USE my_database

Note: InfluxQL is the original query language for InfluxDB 1.x. In InfluxDB 2.x it is supported via the /api/v2/query and /query (v1) compatibility endpoints, provided a DBRP mapping exists. InfluxDB 3 Core/Enterprise (GA 2025) re-introduces native InfluxQL alongside SQL on the new FDAP (Arrow/DataFusion/Parquet) engine, though some 1.x-only statements (continuous queries, retention policy DDL, kapacitor-style features) are not available.

HTTP API Connection

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# InfluxDB 1.x — /query endpoint
curl -G 'http://localhost:8086/query' \
     --data-urlencode "db=my_database" \
     --data-urlencode "q=SELECT * FROM measurement LIMIT 10"

# InfluxDB 2.x — /query (v1 compatibility) with token auth
curl -G 'http://localhost:8086/query' \
     -H "Authorization: Token <INFLUX_TOKEN>" \
     --data-urlencode "db=my_database" \
     --data-urlencode "q=SELECT * FROM measurement LIMIT 10"

# InfluxDB 3 — InfluxQL over the v3 query API
curl -G 'http://localhost:8181/api/v3/query_influxql' \
     -H "Authorization: Bearer <INFLUX_TOKEN>" \
     --data-urlencode "db=my_database" \
     --data-urlencode "q=SELECT * FROM measurement LIMIT 10"

Popular InfluxDB Clients

• Python: influxdb-client (v2/v3) — influxdb-python is legacy (1.x only)
• Go: influxdb-client-go/v2, influxdb3-go (v3)
• Node.js: @influxdata/influxdb-client, @influxdata/influxdb3-client
• Java: influxdb-client-java, influxdb3-java
• C#/.NET: InfluxDB.Client, InfluxDB3.Client
• Arrow Flight SQL drivers also work with InfluxDB 3 for SQL/InfluxQL access

2. Time-Series Database Concepts

Key Components

• Measurement: Similar to a table (e.g., cpu_usage, temperature)
• Tags: Indexed string metadata (e.g., host, region) — used for filtering and grouping
• Fields: Typed data values (float, integer, string, boolean) — not indexed in 1.x/2.x; columnar/indexed in 3.x
• Timestamp: Nanosecond-precision time of each point

Example Data Point (Line Protocol)

3. Basic InfluxQL Syntax

Query Structure

1
2
3
4
5
6
7
8
9
10
11
SELECT <fields>
FROM <measurement>
WHERE <condition>
GROUP BY <tags>
ORDER BY time [ASC|DESC]
LIMIT <number>
OFFSET <number>
SLIMIT <series-limit>
SOFFSET <series-offset>
TZ('America/Los_Angeles')

4. Data Insertion (Line Protocol)

Line Protocol Format

Example Insertions

1
2
3
4
5
6
7
-- Write via 1.x CLI
INSERT cpu_usage,host=server01 value=65.4

-- Multiple points (1.x CLI)
INSERT temperature,location=kitchen temp=22.5
INSERT temperature,location=bedroom temp=20.3

1
2
3
4
5
6
7
8
9
10
# Preferred ingestion path for 2.x / 3.x — /api/v2/write
curl -XPOST 'http://localhost:8086/api/v2/write?bucket=my_database&precision=ns' \
     -H "Authorization: Token <INFLUX_TOKEN>" \
     --data-binary 'cpu_usage,host=server01 value=65.4 1600000000000000000'

# InfluxDB 3 — /api/v3/write_lp (supports tag/field schema-on-write)
curl -XPOST 'http://localhost:8181/api/v3/write_lp?db=my_database&precision=nanosecond' \
     -H "Authorization: Bearer <INFLUX_TOKEN>" \
     --data-binary 'cpu_usage,host=server01 value=65.4'

5. SELECT Queries with Time-Based Filtering

Time Range Queries

1
2
3
4
5
6
7
8
9
10
11
12
13
14
-- Last hour of data
SELECT * FROM cpu_usage
WHERE time > now() - 1h

-- Specific RFC3339 time range
SELECT * FROM temperature
WHERE time >= '2025-01-01T00:00:00Z'
  AND time <= '2025-01-02T00:00:00Z'

-- Relative window with timezone
SELECT mean("temp") FROM temperature
WHERE time > now() - 7d
GROUP BY time(1h) TZ('Europe/Berlin')

6. Aggregation Functions

Common Aggregations

1
2
3
4
5
6
7
8
9
10
11
12
-- Mean value
SELECT MEAN("value") FROM cpu_usage WHERE time > now() - 1h

-- Multiple aggregations
SELECT
  MEAN("value")  AS avg_cpu,
  MAX("value")   AS peak_cpu,
  MIN("value")   AS low_cpu,
  COUNT("value") AS total_measurements
FROM cpu_usage
WHERE time > now() - 1d

Available aggregators include MEAN, MEDIAN, MODE, SUM, COUNT, DISTINCT, INTEGRAL, SPREAD, STDDEV, PERCENTILE, FIRST, LAST, MIN, MAX, plus selectors like TOP, BOTTOM, SAMPLE. Transformations include DERIVATIVE, NON_NEGATIVE_DERIVATIVE, DIFFERENCE, MOVING_AVERAGE, CUMULATIVE_SUM, ELAPSED. (Predictive functions such as HOLT_WINTERS are 1.x-only and not implemented in InfluxDB 3.)

7. Time-Based Grouping

Aggregation by Time Intervals

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
-- Hourly aggregation
SELECT MEAN("value") AS avg_temp
FROM temperature
WHERE time > now() - 1d
GROUP BY time(1h)

-- Custom bucket with gap fill
SELECT MEAN("value") AS avg_temp
FROM temperature
WHERE time > now() - 6h
GROUP BY time(30m) FILL(previous)

-- Offset the bucket boundary
SELECT MEAN("value") FROM temperature
WHERE time > now() - 1d
GROUP BY time(1h, 15m)

FILL accepts none, null, previous, linear, or a literal value. A WHERE time predicate is required for GROUP BY time(...) queries.

8. Continuous Queries

Auto-Aggregation (InfluxDB 1.x only)

1
2
3
4
5
6
7
8
9
CREATE CONTINUOUS QUERY cq_1h_mean
ON my_database
BEGIN
  SELECT MEAN("value") AS mean_value
  INTO "aggregated_metrics"
  FROM "cpu_usage"
  GROUP BY time(1h), host
END

Deprecated in 2.x / 3.x. Continuous queries are not available in InfluxDB 2.x (use tasks written in Flux) or InfluxDB 3 (use processing engine plug-ins, scheduled tasks, or downsampling via SQL INSERT ... SELECT). Plan migrations off CQs when upgrading.

9. Retention Policies

Managing Data Retention (InfluxDB 1.x)

1
2
3
4
5
6
7
8
CREATE RETENTION POLICY "two_weeks"
ON "my_database"
DURATION 2w REPLICATION 1 DEFAULT

ALTER RETENTION POLICY "two_weeks"
ON "my_database"
DURATION 4w

In InfluxDB 2.x, retention is configured per bucket (influx bucket update --retention …). In InfluxDB 3, retention is set on databases via influxdb3 create database --retention-period or the management API. Retention-policy DDL via InfluxQL is only meaningful against the 1.x compatibility layer where a DBRP mapping exists.

10. Mathematical and Conditional Functions

Mathematical Operations

1
2
3
4
5
6
7
8
9
10
-- Arithmetic and math functions
SELECT
  "value" * 1.5      AS adjusted_value,
  SQRT("value")      AS root_value,
  ABS("value")       AS abs_value,
  LN("value")        AS ln_value,
  ROUND("value")     AS rounded
FROM metrics
WHERE time > now() - 1h

Other supported math/scalar functions: EXP, LOG, LOG2, LOG10, POW, FLOOR, CEIL, SIN, COS, TAN, ASIN, ACOS, ATAN, ATAN2.

1
2
3
4
5
6
7
-- Conditional values via CASE-like selector
SELECT
  ABS("value") AS magnitude,
  PERCENTILE("value", 95) AS p95
FROM metrics
WHERE time > now() - 1h

InfluxQL does not include generic string manipulation functions such as LOWER, UPPER, or CONCAT. Reshape string data at ingestion time or, in InfluxDB 3, use SQL with DataFusion string functions.

11. Subqueries and Nested Queries

Complex Querying

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
-- Aggregate over a filtered inner query
SELECT MEAN("value")
FROM (
  SELECT "value"
  FROM cpu_usage
  WHERE host = 'server01' AND time > now() - 1h
)

-- Filter an aggregated time series
SELECT *
FROM (
  SELECT MEAN("value") AS avg_value
  FROM cpu_usage
  WHERE time > now() - 1d
  GROUP BY time(1h)
)
WHERE avg_value > 70

Subqueries must appear in the FROM clause and follow the same time-bound rules as the outer query.

12. Schema Exploration

Metadata Queries

1
2
3
4
5
6
7
8
9
10
SHOW DATABASES
SHOW MEASUREMENTS
SHOW MEASUREMENTS WITH MEASUREMENT =~ /^cpu/
SHOW SERIES FROM cpu_usage WHERE host = 'server01'
SHOW SERIES CARDINALITY
SHOW TAG KEYS FROM cpu_usage
SHOW TAG VALUES FROM cpu_usage WITH KEY = "host"
SHOW FIELD KEYS FROM temperature
SHOW RETENTION POLICIES ON my_database   -- 1.x only

13. Performance Optimization

Query Performance Tips

• Always include a bounded WHERE time … predicate
• Filter on tag keys (indexed in 1.x/2.x; dictionary-encoded in 3.x)
• Avoid SELECT * on wide measurements
• Project only the fields you need
• Prefer aggregations over raw scans for dashboards
• Use SLIMIT/SOFFSET to page series
• Monitor cardinality (SHOW SERIES CARDINALITY); high-cardinality tags are the most common performance killer
• In InfluxDB 3, the Parquet/Arrow engine benefits from larger time ranges and column projection; avoid WHERE predicates on fields when a tag works

Example Optimized Query

1
2
3
4
5
6
7
SELECT MEAN("value")
FROM cpu_usage
WHERE host = 'server01'
  AND time > now() - 1d
GROUP BY time(5m)
FILL(none)

14. IoT and Monitoring Patterns

Common Use Cases

• Device health monitoring
• Environmental sensing
• Industrial / OT telemetry
• Network and APM performance tracking
• Energy and utility metering

Sample IoT Query

1
2
3
4
5
6
7
8
9
SELECT
  MEAN("temperature") AS avg_temp,
  MAX("humidity")     AS peak_humidity
FROM sensor_data
WHERE "device_type" = 'environmental'
  AND time > now() - 24h
GROUP BY time(1h), "device_id"
FILL(none)

15. Visualization Integration

Grafana

1. Add an InfluxDB data source — choose InfluxQL as the query language (alternatives: Flux for 2.x, SQL for 3.x)
2. For 2.x/3.x, configure token auth and a DBRP-mapped database name
3. Use template variables like $measurement, $tag_host, and $__interval
4. Use $timeFilter in the WHERE clause to bind to the dashboard time range

Chronograf and Successors

• Chronograf ships with InfluxDB 1.x and remains in maintenance mode
• InfluxDB 2.x uses the built-in Data Explorer and Dashboards UI
• InfluxDB 3 focuses on Grafana, Superset, and BI tools via Flight SQL; the bundled UI is intentionally minimal
• Kapacitor alerting is 1.x-only — for 2.x use tasks + checks/notifications; for 3.x use processing engine plug-ins or external alerting (Grafana Alerting, Prometheus Alertmanager)

Pro Tips

• Always bound queries with a WHERE time predicate
• Right-size retention policies / bucket retention before ingest grows
• Watch series cardinality — keep high-churn identifiers in fields, not tags
• Pre-aggregate hot dashboards (CQs in 1.x, tasks in 2.x, scheduled SQL/processing engine in 3.x)
• Use tags for predicates and GROUP BY, fields for measurements and math
• Prefer the newer influxdb-client-* libraries; the original influxdb-python client is feature-frozen
• When migrating off 1.x, audit usage of CQs, retention DDL, and string functions — these have no direct InfluxQL replacement in 3.x

Resources

• InfluxData Docs — InfluxQL reference (1.x, 2.x compatibility, 3 Core/Enterprise)
• InfluxData Community Forums and Discord
• GitHub: influxdata/influxdb, influxdata/influxdb_iox, influxdata/influxdb3_core
• InfluxDB University (free training)
• Telegraf plugin catalog for ingest pipelines