Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 39 ยท Performance and Scaling

Series Cardinality Explained

Understand series cardinality in time-series databases, how tag choices multiply it, why high cardinality hurts, and how to find and fix it. Runnable examples.

Ask an experienced InfluxDB operator what makes a deployment slow or unstable and one word comes up first: cardinality. It decides memory use, index size and query speed more than raw data volume does. Understanding it before you design your schema saves painful migrations later.

This lesson defines a series, shows how tags multiply series counts, explains why high cardinality is costly (and how InfluxDB 3 changes the picture), and gives you tools to measure and reduce it. The server cannot run here, so counting is demonstrated with SQL and JavaScript on sample data.

What a series is

In InfluxDB's data model a series is a unique combination of measurement, tag set and (in 2.x and 1.x) field key. Take these points:

TEXT
cpu,host=web-1,region=eu usage=41.2
cpu,host=web-1,region=eu usage=44.0
cpu,host=web-2,region=eu usage=39.5
cpu,host=web-1,region=us usage=50.1

There are three series: (web-1, eu), (web-2, eu) and (web-1, us). The number of points inside a series does not matter. Series cardinality is the total number of distinct series in a database or bucket.

Tags are indexed, and every distinct combination creates an index entry. Fields are not indexed. That is why choosing what becomes a tag is the single most important schema decision (see schema design).

How tags multiply

If tags are independent, the maximum number of series is the product of each tag's distinct values:

series = hosts x regions x services x ...

100 hosts, 5 regions and 20 services allow up to 10,000 series per field. Add a request_id tag with a new value for every request and the count grows without bound. That is the classic mistake: putting a unique or very-high-variety value (user ID, session ID, URL with query string, container ID in a churning cluster) into a tag.

JS Stand-in: how fast tag combinations multiply

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

No output.

In reality not every combination occurs (a given host is in one region), so actual cardinality is lower than the product. But the product is the upper bound that planners use.

flowchart TD
  M["measurement: cpu"] --> H["host: 500 values"]
  H --> R["region: 6 values"]
  R --> S["service: 40 values"]
  S --> X["up to 120,000,000 series if every combination occurs"]

Each extra tag multiplies the potential number of series.

Why high cardinality hurts

For InfluxDB 1.x and 2.x (the TSM engine):

  • The series index (TSI) must hold every series key. Large indexes use more memory and take longer to start.
  • Each series has bookkeeping overhead, so many tiny series cost far more than few large ones with the same number of points.
  • Queries that touch many series do more index lookups and merge more files.
  • Compaction and writes slow down as the index grows.

InfluxDB 3 stores data in a columnar format (Apache Arrow in memory, Parquet on disk). It is designed to handle high-cardinality data far better, because tags are ordinary columns rather than entries in an in-memory inverted index. That does not make the choice free: every extra column, extra distinct value and wider row still costs storage and scan time, and very high-cardinality grouping queries remain expensive. Treat "unlimited cardinality" as "much more forgiving", not "ignore it".

Measuring cardinality

With a server you could run, in Flux (read-only):

JavaScript
import "influxdata/influxdb"

influxdb.cardinality(start: -30d, predicate: (r) => r._measurement == "cpu")

In InfluxQL, SHOW SERIES CARDINALITY and SHOW TAG VALUES CARDINALITY WITH KEY = "host" do the same job. In InfluxDB 3 SQL you can count distinct tag combinations directly. The SQL stand-in below shows the technique on a small table: it counts distinct series, distinct values per tag, and finds the tag that contributes most.

SQL Stand-in: count series and find the worst tag

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

Treating request_id as a tag turns 5 series into 1,000, one per point. That is the sign of a mis-designed tag: a "series" with only one point is not a series, it is a row.

Fixing high cardinality

  1. Move unbounded values to fields. request_id, user_id and similar identifiers belong in a field if you must store them at all.
  2. Drop what you never filter by. If nobody ever groups by container_id, do not store it as a tag.
  3. Normalise values. Strip query strings from URLs; use route templates (/users/:id) instead of full paths.
  4. Bucket continuous values. Do not tag latitude and longitude; use a coarse region, or put coordinates in fields.
  5. Keep ephemeral identifiers out. In orchestrated clusters, pod and container names churn; tag the stable service name instead.
  6. Split data by lifetime. Put churny data in a bucket with short retention, so old series expire (see retention).
  7. Aggregate at the edge. Send per-service totals instead of per-request lines.

Rule of thumb

If you would never write WHERE tag = 'x' or GROUP BY tag on a value, and the number of distinct values keeps growing over time, it should not be a tag.

Common mistakes

  • Using a timestamp-like or ID value as a tag.
  • Tagging with free text such as error messages.
  • Letting the same measurement receive two different tag sets from different agents, which doubles series.
  • Ignoring series churn: old series deleted and new ones created constantly can be as harmful as a big static set.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What defines a series in InfluxDB 2.x?

    A series is a unique combination of measurement, tag set and field key. Many points can live in one series.
  2. 2. 100 hosts, 5 regions and 20 services (all combinations occurring) allow how many series per field?

    100 x 5 x 20 = 10,000.
  3. 3. Where should a per-request unique ID go?

    Unbounded identifiers as tags explode the series index. Fields are not indexed.
  4. 4. How does InfluxDB 3 treat high cardinality compared with 1.x/2.x?

    The columnar design handles it far better, but design still matters.

Summary

  • A series is a unique measurement + tag set (+ field key); cardinality is how many exist.
  • Tag value counts multiply, so one runaway tag can dominate.
  • High cardinality inflates index memory and slows writes and queries in TSM-based versions.
  • Measure it, then move unbounded values to fields, normalise values, and drop unused tags.
  • InfluxDB 3 is more forgiving, not free.

Next: Schema Design for Performance