influxdb

name	InfluxDB
description	Store and query time-series data with proper schema design and retention.
metadata	{"clawdbot":{"emoji":"📈","requires":{"anyBins":["influx","curl"]},"os":["linux","darwin","win32"]}}

Version Differences

• InfluxDB 2.x uses Flux query language, 1.x uses InfluxQL—syntax completely different
• 2.x: buckets, organizations, tokens; 1.x: databases, retention policies, users
• Don't mix documentation—check version before copying queries

Tags vs Fields (Critical)

• Tags are indexed, fields are not—filter on tags, aggregate on fields
• Tag values must be strings—numbers as tags work but waste index space
• Fields support numbers, strings, booleans—store metrics as fields
• Wrong choice kills query performance—can't change after data written

Cardinality Trap

• High-cardinality tags destroy performance—unique user IDs as tags = disaster
• Cardinality = unique combinations of tag values—grows multiplicatively
• Check with SHOW CARDINALITY (1.x) or influx bucket inspect (2.x)
• Rule of thumb: <100K series per measurement; millions = problems

Line Protocol

• Format: measurement,tag1=v1,tag2=v2 field1=1,field2="str" timestamp
• No spaces around = in tags—space separates tags from fields
• String fields need quotes, tag values don't—field="text" vs tag=text
• Timestamps in nanoseconds by default—specify precision to avoid mistakes

Timestamps

• Default precision is nanoseconds—sending seconds without precision flag = year 2000 data
• Specify on write: precision=s for seconds, precision=ms for milliseconds
• Missing timestamp uses server time—usually fine for real-time ingestion
• Timestamps are UTC—client timezone doesn't matter

Retention and Downsampling

• Set retention policy/bucket duration—data older than retention auto-deleted
• Raw data at 10s intervals for 7 days, downsample to 1min for 30 days, 1h for 1 year
• 2.x: Tasks for downsampling; 1.x: Continuous Queries
• Without downsampling, storage grows forever and queries slow down

Flux Query Patterns (2.x)

• Always start with from(bucket:) then |> range(start:)—range is required
• |> filter(fn: (r) => r._measurement == "cpu") for filtering
• |> aggregateWindow(every: 1h, fn: mean) for time-based aggregation
• Chain transforms with |> pipe operator—order matters for performance

InfluxQL Patterns (1.x)

• SELECT mean("value") FROM "measurement" WHERE time > now() - 1h GROUP BY time(5m)
• Double quotes for identifiers, single quotes for string literals
• GROUP BY time() for time-based aggregation—required for most dashboards
• FILL(none) to skip empty intervals, FILL(previous) to carry forward

Schema Design

• Measurement name = table name—one per metric type (cpu, memory, requests)
• Tag for dimensions you filter/group by—host, region, service
• Field for values you aggregate—usage_percent, count, latency_ms
• Avoid encoding data in measurement names—cpu.host1 wrong, cpu + host=host1 right

Write Performance

• Batch writes—individual points have HTTP overhead
• Telegraf for production ingestion—handles batching, buffering, retry
• Write to localhost if possible—network latency adds up at high throughput
• async writes in client libraries—don't block on each write

Query Performance

• Always include time range—unbounded queries scan everything
• Filter on tags before fields—tags use index, fields scan data
• Limit results with LIMIT or |> limit()—dashboard doesn't need 1M points
• Use GROUP BY / aggregateWindow to reduce data before returning

Common Errors

• "partial write: field type conflict"—same field with different types; fix at source
• "max-values-per-tag limit exceeded"—cardinality too high; redesign schema
• "database not found"—2.x uses buckets, not databases; check API version
• Query timeout—add narrower time range or aggregate more aggressively