Time Seriesintermediate

InfluxDB Data Model

Measurements, tags, fields and the version differences that make InfluxDB documentation version-specific.

2 min readIntermediateUpdated 31 Jul 2026Edit this page

InfluxDB organises data into measurements containing points, each with a timestamp, tags and fields.

readings,device_id=d-1001,region=eu temperature=21.4,humidity=48.2 1753968000000000000
└────────┘└──────────── tags ─────┘└────────── fields ──────────┘└─── timestamp ───┘

The distinction is the most important thing to understand:

	Tags	Fields
Indexed	Yes	No
Filterable efficiently	Yes	Only by scanning
Part of the series key	Yes	No
Affects cardinality	Yes	No
Data types	Strings only	Float, integer, string, boolean

SHOW SERIES CARDINALITY;
SHOW TAG KEY CARDINALITY;
SHOW TAG VALUES CARDINALITY WITH KEY = "device_id";

Version differences matter more here than elsewhere

InfluxDB has changed substantially across major versions:

1.x — the TSM storage engine, InfluxQL query language, databases and retention policies.
2.x — Flux as the primary language, buckets replacing databases and retention policies, a built-in task engine and UI.
3.x — a rebuilt engine based on Apache Arrow, DataFusion and Parquet, with SQL support.

Schema design

Keep tag cardinality bounded. Tags are for dimensions you filter and group by, with a limited value set: region, environment, device type, status.

Put unbounded values in fields. They are still stored and returned; they simply are not indexed and do not multiply the series space.

Use several measurements rather than one wide one. Grouping unrelated metrics into a single measurement forces every query to filter more than it needs.

Write in batches, with a consistent timestamp precision. Sending nanosecond precision when you have second-resolution data wastes space and compresses worse:

curl -XPOST "http://influxdb:8086/api/v2/write?bucket=metrics&precision=s" \
  --data-binary @batch.lp

Retention

Retention is configured per bucket (2.x and later) or per retention policy (1.x). Expired data is removed by dropping whole shards, so it is inexpensive — the same partition-drop mechanism used by other time-series engines.

Downsampling is implemented with scheduled tasks that aggregate into a second bucket with a longer retention period. Keep the downsampled bucket longer than the raw one; that is the entire point of the arrangement.