Introduction
Understanding InfluxDB’s internal architecture helps you design better schemas, optimize queries, and troubleshoot performance issues. InfluxDB uses specialized data structures optimized for time-series data: the TSM (Time-Structured Merge) storage engine. This article explores the key components that make InfluxDB efficient at handling high-volume time-series data.
Storage Architecture
TSM Storage Engine
InfluxDB uses TSM (Time-Structured Merge) - a storage engine optimized for time-series data:
┌─────────────────────────────────────────────────────────────┐
│ InfluxDB │
├─────────────────────────────────────────────────────────────┤
│ Query Engine │ Write Path │ Storage Engine │
│ │ │ │
│ - InfluxQL │ - Line Proto │ - TSM │
│ - Functions │ - Parser │ - WAL │
│ - Aggregations │ - Write API │ - Shards │
│ │ │ - Compression │
└─────────────────────────────────────────────────────────────┘
Key Components
- WAL (Write-Ahead Log): First stop for incoming data
- Cache: In-memory buffer for recent writes
- TSM Files: Columnar storage on disk
- Shard: Organized by retention policy and time range
Write Path
When data is written to InfluxDB:
-- Write operation
INSERT cpu,host=server01 value=0.5
The write path:
- WAL Write: Data written to WAL immediately
- Cache Update: Data added to in-memory cache
- Response: Client receives confirmation
// Simplified write flow
func (w *Writer) WritePoint(p *Point) error {
// 1. Write to WAL
w.wal.Write(p)
// 2. Update cache
w.cache.Add(p)
// 3. Return success
return nil
}
Shard Management
Shards organize data by time range and retention policy:
-- View shards
SHOW SHARDS
-- Create retention policy with shard duration
CREATE RETENTION POLICY "one_week" ON "mydb"
DURATION 1w
SHARD DURATION 1d
REPLICATION 1
Shard Structure
/var/lib/influxdb/data/mydb/one_week/
├── 000000001-000000001.tsm # TSM file
├── 000000002-000000002.tsm
├── 000000003-000000003.tsm
└── .index # Index file
Each shard contains:
- Multiple TSM files
- Index for fast lookups
- Min/Max time indices
TSM File Format
TSM (Time-Structured Merge) files store data efficiently:
┌────────────────────────────────────┐
│ TSM File │
├────────────────────────────────────┤
│ Header (Magic, Version) │
├────────────────────────────────────┤
│ Index Block │
│ ┌──────┬──────┬──────┬──────┐ │
│ │Col 1 │Col 2 │Col 3 │ ... │ │
│ └──────┴──────┴──────┴──────┘ │
├────────────────────────────────────┤
│ Data Block 1 (columnar) │
│ ┌──────────────────────────────┐ │
│ │ Timestamps │ │
│ ├──────────────────────────────┤ │
│ │ Values │ │
│ └──────────────────────────────┘ │
├────────────────────────────────────┤
│ Data Block 2 │
└────────────────────────────────────┘
Compression
TSM uses multiple compression algorithms:
| Data Type | Compression |
|---|---|
| Timestamps | Delta-of-delta encoding |
| Float values | Gorilla compression |
| Integers | RLE or snappy |
| Strings | Snappy compression |
Example compression effectiveness:
-- Query shows compression ratio
SHOW SERIES CARDINALITY ON mydb
-- InfluxDB internally compresses:
-- Raw: 1,000,000 points × 8 bytes = 8 MB
-- Compressed: ~0.5 MB (16:1 ratio typical)
WAL (Write-Ahead Log)
The WAL ensures durability:
// WAL structure
type WAL struct {
// Write-ahead log files
// Each entry is encoded point data
// fsynced before acknowledging write
}
Properties:
- Append-only
- Memory-mapped files
- Crash-safe
- Size: ~10MB per file
Query Execution
Query Flow
SELECT mean(value) FROM cpu WHERE time > now() - 1h GROUP BY time(5m)
Steps:
- Parse: Parse InfluxQL to AST
- Plan: Create execution plan
- Read: Read from TSM files
- Aggregate: Apply aggregation
- Return: Return results
Query Planning
-- EXPLAIN shows query plan
EXPLAIN SELECT mean(value) FROM cpu
-- Result:
-- Plan: MapReadGroup -> MeanReducer -> HTTPResponse
Time-Based Pruning
InfluxDB efficiently skips irrelevant data:
-- Query with time filter
SELECT * FROM cpu WHERE time > now() - 1h
-- InfluxDB:
-- 1. Check shard time ranges
-- 2. Skip shards outside time range
-- 3. Use index to find relevant blocks
Caching
In-memory cache for recent reads:
# Cache configuration
[storage]
cache-max-memory-size = "8g"
cache-snapshot-memory-size = "1g"
cache-snapshot-write-cold-duration = "10m"
Cache Structure
// Cache entry
type CacheEntry struct {
SeriesID uint64
Values []Value // sorted by timestamp
}
Cache behavior:
- Sorted by series key + timestamp
- Flushed to TSM when full or after duration
- Compacts during flush
Compaction
Background process to optimize storage:
// Compaction levels
const (
Level0Compaction = iota // Minor, within shard
Level1Compaction // Merge TSM files
Level2Compaction // Major merge
FullCompaction // Full optimization
)
Compaction Triggers
[compaction]
max-concurrent-compactions = 4
compact-throughput = "50m"
compact-throughput-burst = "100m"
Index Architecture
Series Index
InfluxDB maintains a series index:
-- Show all series
SHOW SERIES ON mydb
-- Series cardinality
SHOW SERIES CARDINALITY ON mydb
-- Index on tags creates series
CREATE INDEX ON cpu (host) -- Creates series: cpu,host=server01
CREATE INDEX ON cpu (region) -- Creates series: cpu,region=us-west
Tag Index
Tag lookups are optimized:
// Tag index structure
type TagIndex struct {
// Maps tag values to series IDs
// Fast O(1) lookups
}
Memory Management
Understanding memory usage:
# View memory usage
curl http://localhost:8086/debug/vars | jq '.memstats'
# Key metrics
# - Alloc: Current memory allocated
# - Sys: Total memory from OS
# - NumGC: Number of garbage collections
Memory pools:
- Series index: Maps series keys to IDs
- Field index: Maps fields to types
- Cache: Recent time-series data
- WAL buffer: Write-ahead log
Query Performance Characteristics
| Operation | Complexity |
|---|---|
| Point lookup by timestamp | O(log n) |
| Range query | O(k + n) where k = blocks scanned |
| Aggregation | O(n) |
| GROUP BY time | O(n) |
| JOIN | O(n × m) |
Optimizing Queries
-- Good: Use time filter
SELECT * FROM cpu WHERE time > now() - 1h
-- Bad: No time filter (full scan)
SELECT * FROM cpu
-- Good: Limit fields
SELECT host, value FROM cpu
-- Bad: Select all fields
SELECT * FROM cpu
Data Retention
Automatic data lifecycle:
-- Create retention policy
CREATE RETENTION POLICY "one_day" ON "mydb"
DURATION 1d
SHARD DURATION 1h
REPLICATION 1
-- View retention policies
SHOW RETENTION POLICIES ON mydb
Shard duration determines data granularity:
- Short duration: More shards, faster deletes
- Long duration: Fewer shards, better compression
Conclusion
InfluxDB’s architecture is optimized for time-series workloads. The TSM storage engine provides efficient compression, the WAL ensures durability, and intelligent query planning minimizes IO. Understanding these internals helps you design schemas that leverage these optimizations: use appropriate time ranges, minimize series cardinality, and filter by time in queries.
In the next article, we’ll explore recent InfluxDB developments and trends for 2025-2026.
Comments