PromQL Limitations

Overview

Kloudfuse enforces hard limits on query result size to protect cluster stability. Some query patterns — particularly over_time functions applied to large metric sets, and binary join operations — carry additional performance costs that are worth understanding before writing production queries or alerts.

Series and data point limits

Kloudfuse caps both the number of time series and the number of individual data points returned by a single query.

  • Maximum series per query result: 10,000. Queries that would match more series are rejected with an error before evaluation.

  • Maximum data points per query: 5,000,000. A query over a long time range with many series will hit this limit even if each individual series is short.

To stay within limits:

  • Add label matchers to narrow the series selection: {namespace="prod", service="api"} instead of bare metric names.

  • Use aggregation operators before passing data to expensive functions: sum by (service) (rate(…​)) rather than passing every pod series.

  • Reduce query range or increase step interval for exploratory queries in dashboards.

Over_time function performance

Over_time functions (avg_over_time, max_over_time, etc.) evaluate a range window for every series in the result. Cost scales linearly with:

  • Number of matching series — the function runs once per series.

  • Window size — a wider window loads more raw samples per series.

  • Step count — dashboards evaluate the query at every step across the chart range, multiplying the work by the number of steps.

Subquery cost

When an over_time function is given a subquery expression (func(<expr>[<range>:<step>])) rather than a raw metric selector, the inner expression is evaluated from scratch at every step within the subquery window before the outer function aggregates the results. This can multiply evaluation work significantly:

# This evaluates rate() at every 1m step inside a 1h window — 60 inner evaluations per series
max_over_time(rate(http_requests_total[5m])[1h:1m])

Guidance for subqueries:

  • Keep the subquery <step> as coarse as the use case allows. A 5-minute step for a 6-hour window (72 inner evaluations) is far cheaper than a 1-minute step (360 inner evaluations).

  • Aggregate the inner expression down to fewer series before wrapping it in an over_time function.

  • Avoid omitting <step> entirely — when step is omitted, the global evaluation interval is used, which in a dashboard may be as fine as 10 or 15 seconds.

Join (binary operator) performance

Binary operators that match series from two sides of an expression (on(…​) or ignoring(…​)) perform an in-memory join. Performance degrades when either side has high cardinality:

  • O(n × m) matching — every series on the left is matched against every series on the right for the common labels. With thousands of series on both sides this can be slow.

  • Memory pressure — both sides must be held in memory simultaneously during evaluation.

Guidance for joins:

  • Aggregate to the lowest useful label set before joining: sum by (service) (metric_a) / sum by (service) (metric_b) instead of joining at pod or instance cardinality.

  • Use on(…​) to restrict matching labels explicitly rather than relying on ignoring(…​) — it avoids cross-matching on unintended label dimensions.

  • Avoid one-to-many and many-to-many joins (group_left, group_right) on high-cardinality series unless the left or right side has already been aggregated to a small set.

Algorithmic function limits

The Kloudfuse advanced functions (SARIMA, Prophet, DBSCAN, etc.) fit a model per input series and run in a separate advanced-functions service. Because model fitting is compute-intensive, these functions are more sensitive to series count than standard PromQL operators.

  • Aggregate to the label dimensions you need before passing series to an advanced function.

  • Avoid applying advanced functions to raw, unaggregated counters or gauges with per-pod or per-instance labels.

See Algorithmic functions for syntax and AI and ML Capabilities for model details.