Resolve high series cardinality
If reads and writes to InfluxDB have started to slow down, high series cardinality (too many series) may be causing memory issues.
To resolve high series cardinality, complete the following steps (for multiple buckets if applicable):
Review tags
Review your tags to ensure each tag does not contain unique values for most entries:
- Scan your tags for common tag issues.
- Use the example Flux query below to count unique tag values.
Common tag issues
Look for the following common issues, which often cause many unique tag values:
- Writing log messages to tags. If a log message includes a unique timestamp, pointer value, or unique string, many unique tag values are created.
- Writing timestamps to tags. Typically done by accident in client code.
- Unique tag values that grow over time For example, a user ID tag may work at a small startup, but may begin to cause issues when the company grows to hundreds of thousands of users.
Count unique tag values
The following example Flux query shows you which tags are contributing the most to cardinality. Look for tags with values orders of magnitude higher than others.
// Count unique values for each tag in a bucket
import "influxdata/influxdb/schema"
cardinalityByTag = (bucket) =>
schema.tagKeys(bucket: bucket)
|> map(fn: (r) => ({
tag: r._value,
_value:
if contains(set: ["_stop","_start"], value:r._value) then 0
else (schema.tagValues(bucket: bucket, tag: r._value)
|> count()
|> findRecord(fn: (key) => true, idx: 0))._value
}))
|> group(columns:["tag"])
|> sum()
cardinalityByTag(bucket: "example-bucket")
If you’re experiencing runaway cardinality, the query above may timeout. If you experience a timeout, run the queries below—one at a time.
Generate a list of tags:
// Generate a list of tags import "influxdata/influxdb/schema" schema.tagKeys(bucket: "example-bucket")
Count unique tag values for each tag:
// Run the following for each tag to count the number of unique tag values import "influxdata/influxdb/schema" tag = "example-tag-key" schema.tagValues(bucket: "my-bucket", tag: tag) |> count()
These queries should help to identify the sources of high cardinality in each of your buckets. To determine which specific tags are growing, check the cardinality again after 24 hours to see if one or more tags have grown significantly.
Adjust your schema
Usually, resolving high cardinality is as simple as changing a tag with many unique values to a field. Review the following potential solutions for resolving high cardinality:
- Delete data to reduce high cardinality
- Design schema or read performance
Delete data to reduce high cardinality
Consider whether you need the data causing high cardinality. In some cases, you may decide you no longer need this data, in which case you may choose to delete the whole bucket or delete a range of data.
Design schema for read performance
Tags are valuable for indexing, so during a query, the query engine doesn’t need to scan every single record in a bucket. However, too many indexes may create performance problems. The trick is to create a middle ground between scanning and indexing.
For example, if you query for specific user IDs with thousands of users, a simple query like this, where userId
is a field, requires InfluxDB to scan every row for the userId
:
from(bucket: "example-bucket")
|> range(start: -7d)
|> filter(fn: (r) => r._field == "userId" and r._value == "abcde")
If you include a tag in your schema that can be reasonably indexed, such as a company
tag, you can reduce the number of rows scanned and retrieve data more quickly:
from(bucket: "example-bucket")
|> range(start: -7d)
|> filter(fn: (r) => r.company == "Acme")
|> filter(fn: (r) => r._field == "userId" and r._value == "abcde")
Consider tags that can be reasonably indexed to make your queries more performant. For more guidelines to consider, see InfluxDB schema design.
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB and this documentation. To find support, the following resources are available:
InfluxDB Cloud and InfluxDB Enterprise customers can contact InfluxData Support.