Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 39 ยท Concepts and Data Model

Series and Cardinality

Learn what series cardinality is, how to calculate it from tag values, why high cardinality hurts, and practical schema rules that keep it under control.

If there is one concept that separates smooth InfluxDB deployments from painful ones, it is series cardinality: the number of distinct series in your database. Each unique combination of a measurement and its tag set is one series, and the database has to track every one of them. A schema that looks harmless on a whiteboard can quietly produce millions of series and slow everything down.

This lesson explains how to count cardinality before you write a single point, why it matters differently in each InfluxDB generation, and the habits that keep it small.

What counts as one series

A series is identified by the measurement name plus the full set of tag key-value pairs. Fields do not count. Look at these three lines:

TEXT
cpu,host=web-01,region=eu usage=41
cpu,host=web-01,region=eu usage=44
cpu,host=web-02,region=eu usage=12

The first two points belong to the same series (same measurement and tags), so they only add a point. The third has a different host, so it is a second series. Cardinality here is 2.

The multiplication rule

If tags are independent, the upper bound on series is the product of the number of distinct values of each tag:

series โ‰ค measurements ร— (values of tag A) ร— (values of tag B) ร— ...

Ten regions, 200 hosts and 5 environments could in theory give 10 ร— 200 ร— 5 = 10,000 series. In practice a host lives in one region and one environment, so the real number is closer to 200. Thinking in terms of the bound, then trimming it with real relationships, gives a reliable estimate.

JS Estimate cardinality before you write (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Why high cardinality hurts

Each series has bookkeeping cost. In InfluxDB 1.x and 2.x an in-memory index (and an on-disk time-series index) tracks every series, so memory use and startup time grow with cardinality. Past a few million series, writes slow down, restarts take minutes and queries that touch many series become expensive. Typical causes:

  • Putting an unbounded or very large value in a tag: user ID, session ID, request ID, full URL, container ID that changes on every deploy, IP address of mobile clients.
  • Churn: series that appear for a while and then never come back (a short-lived container name). The index still remembers them until the retention period removes the data.
  • Encoding values in the measurement or tag key (cpu_web01, tag key metric_17).

InfluxDB 3 stores data in a columnar engine and is designed to cope much better with high cardinality: tags are columns, not entries in a global series index. That is a major reason to choose it for workloads such as per-device or per-user data. Even so, a smaller schema stays cheaper and faster to query, so the habits below still pay off.

Cardinality in practice

This SQLite stand-in loads points with a churn-prone tag and counts the distinct series with count(DISTINCT ...). In InfluxDB you would use SHOW SERIES CARDINALITY (InfluxQL) or influxdb.cardinality() (Flux); those are read-only here.

SQL Count distinct series (SQLite stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Dropping the churn-prone container tag shrinks 150 series to 6 while keeping the questions you actually ask ("latency per host and status") answerable. If you really need the container ID, store it as a field so it does not multiply series.

For the read-only InfluxDB equivalents:

TEXT
-- InfluxQL: how many series in this database?
SHOW SERIES CARDINALITY ON "mydb"

// Flux (2.x): cardinality of a bucket
import "influxdata/influxdb"
influxdb.cardinality(bucket: "my-bucket", start: -30d)

A cardinality checklist

  1. List every tag key and estimate its distinct values for the lifetime of your retention period, not just today.
  2. Reject unbounded tags: IDs, timestamps, free text, anything generated per request.
  3. Check for relationships: if host implies region, you may not need both, or you can keep region because it does not add series (it adds a label to the same series).
  4. Watch churn: ephemeral names (pods, containers, spot instances) multiply series over time. Prefer stable labels such as service or deployment.
  5. Measure: use the cardinality queries above after a trial load. Alert when the number grows unexpectedly.
  6. Fix at the source: it is far easier to change what a collector sends than to clean up a bucket full of stale series.

Cardinality and queries

Cardinality also affects the cost of a query: a query without a tag filter touches every series in the measurement. Always include a time range and, where you can, tag filters, so the engine prunes data early. Querying chapter lessons show how.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What identifies a series?

    Fields do not count; the measurement plus tag key-value pairs define the series.
  2. 2. Which schema design is most dangerous for cardinality?

    An unbounded tag creates a new series for every value.
  3. 3. Tags: host (200 values) and env (5 values), fully independent. What is the upper bound of series?

    200 times 5 equals 1,000 combinations.
  4. 4. What is a good fix for a tag that holds a changing container ID?

    Fields do not multiply series, and stable labels do not churn.

Summary

  • A series is a measurement plus one specific tag set; cardinality is the number of distinct series.
  • The product of tag value counts is an upper bound; real relationships reduce it.
  • High and churning cardinality slows 1.x and 2.x engines and costs money in every generation; 3.x tolerates much more.
  • Keep IDs, free text and ephemeral names out of tags; measure cardinality after a trial load.

Next: Timestamps and Precision