InfluxDBInfluxDB 时序存储

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: INLINECODE2
• No spaces around = in tags—space separates tags from fields
• String fields need quotes, tag values don't—field="text" vs INLINECODE5
• 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
• INLINECODE10 for filtering
• INLINECODE11 for time-based aggregation
• Chain transforms with |> pipe operator—order matters for performance

InfluxQL Patterns (1.x)

• - INLINECODE13
• Double quotes for identifiers, single quotes for string literals
• INLINECODE14 for time-based aggregation—required for most dashboards
• INLINECODE15 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—usagepercent, count, latencyms
• 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
• INLINECODE20 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