Reduce hit timelines to improve query efficiency
Query efficiency in TSDB is directly tied to the number of timelines matched by a query — fewer matched timelines means faster queries. Measure how many timelines your queries currently hit, then use the strategies below to bring that number down.
Measure matched timelines
Use the api/search/lookup endpoint to check how many timelines a query matches:
curl http://localhost:3002/api/search/lookup?m=sys.cpu.usageRun this query before and after applying any optimization to confirm that the matched timeline count has decreased.
Reduce matched timelines
Control the data collection interval
Specify a suitable data collection interval to control the number of matched timelines. A 10-second interval, for example, generates 8,640 data points per timeline per day.
Filter on high-cardinality tags
Tags with many unique values (high cardinality) narrow query results more aggressively than low-cardinality tags. Use high-cardinality tag key-value pairs as the primary filter conditions in your queries.
Example: A setup with 4 data centers, each containing 1,000 IP addresses. Filtering by IP address=172.220.XX.XX matches far fewer timelines than filtering by data center=A, because IP addresses have higher cardinality than data center names.
Common mistakes that create low-cardinality tags: Using tags that represent categorical groupings (region, environment, tier) as filters returns a large fraction of all timelines for that metric. Reserve those tags for grouping, not filtering.
Avoid wildcard queries
Wildcard queries match a large number of timelines and reduce query efficiency. If an exact match isn't possible, use the literal_or filter with the equal-to operator instead.
Pre-aggregate before querying low-cardinality values
Computing an aggregate across many timelines at query time is expensive. Pre-aggregate the data and write the result as a separate timeline — then query that aggregated timeline directly.
Example: To query the maximum CPU usage of data center A (which has 1,000 IP addresses), pre-aggregate the CPU usage data across all 1,000 addresses and write the result as a single aggregated timeline. Query the aggregated timeline instead of all 1,000 individual timelines.