Aggregation & grouping
Reduce across series and choose one grouping strategy.
Aggregation without grouping is valid in both dialects. .by() retains selected labels; .without() drops selected labels. Choose one after the aggregation; do not call both on the same result.
from metricraft import QueryBuilder as Q
aggregate = Q.from_metric("requests_total").rate("5m").sum()
by_service = aggregate.by("service")
without_instance = aggregate.without("instance")
print(by_service.build(mode="promql"))
print(without_instance.build(mode="promql"))Both variants share the original expression. Additional aggregation inputs (*others) require MetricsQL. Numeric parameter recommendations below describe useful backend domains; where no literal bound is enforced by the SDK, that distinction is stated.
Methods and parameters
QueryBuilder
aggregate()Choose an allowlisted non-parameterized aggregation. Apply by() or without() to the returned expression when grouping is needed.
QueryBuilder.aggregate(op: str, *others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
opstrRequired | One of sum, avg, min, max, count, stddev, stdvar, group, any, median, mode, mad, distinct, geomean, histogram, outliers_iqr, share, sum2, zscore. Use dedicated methods for parameterized aggregations. |
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
any()Select one series per MetricsQL aggregation group.MetricsQL only
QueryBuilder.any(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
avg()Compute the arithmetic mean across series in each aggregation group.
QueryBuilder.avg(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
bottomk()Keep the k smallest sample values in each aggregation group, preserving the selected series labels.
QueryBuilder.bottomk(k: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
bottomk_avg()Keep k series with the smallest arithmetic mean across the MetricsQL query interval, optionally collecting remaining series.MetricsQL only
QueryBuilder.bottomk_avg(k: ScalarInput, *, other: Optional[str]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
otherstr | NoneDefault: None | Optional 'label=value' assignment identifying the combined remainder series. None omits it. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
bottomk_last()Keep k series with the smallest last value across the MetricsQL query interval, optionally collecting remaining series.MetricsQL only
QueryBuilder.bottomk_last(k: ScalarInput, *, other: Optional[str]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
otherstr | NoneDefault: None | Optional 'label=value' assignment identifying the combined remainder series. None omits it. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
bottomk_max()Keep k series with the smallest maximum across the MetricsQL query interval, optionally collecting remaining series.MetricsQL only
QueryBuilder.bottomk_max(k: ScalarInput, *, other: Optional[str]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
otherstr | NoneDefault: None | Optional 'label=value' assignment identifying the combined remainder series. None omits it. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
bottomk_median()Keep k series with the smallest median across the MetricsQL query interval, optionally collecting remaining series.MetricsQL only
QueryBuilder.bottomk_median(k: ScalarInput, *, other: Optional[str]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
otherstr | NoneDefault: None | Optional 'label=value' assignment identifying the combined remainder series. None omits it. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
bottomk_min()Keep k series with the smallest minimum across the MetricsQL query interval, optionally collecting remaining series.MetricsQL only
QueryBuilder.bottomk_min(k: ScalarInput, *, other: Optional[str]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
otherstr | NoneDefault: None | Optional 'label=value' assignment identifying the combined remainder series. None omits it. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
by()Group an ungrouped aggregation by exactly these labels, dropping other labels. An empty list forms a single group.
QueryBuilder.by(*labels: str) -> QueryBuilder
Apply exactly one of by()/without(), once, to an ungrouped aggregation. To create both variants, derive them independently from the same aggregate. Omitting grouping is legal in both dialects.
| Parameter / type | Meaning and accepted values |
|---|---|
*labelsstr, ...Variadic | Label names, passed separately. Grouping and matching lists must not contain duplicates. An empty grouping list is allowed; function-specific arity is checked by Rust. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
Example
from metricraft import QueryBuilder as Q
Q.from_metric("requests_total").rate("5m").sum().by("job").build(mode="promql")count()Compute the count across series in each aggregation group.
QueryBuilder.count(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
count_values()Count series by sample value and place each distinct value in an output label.
QueryBuilder.count_values(label: StringInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
labelstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
distinct()Compute the number of distinct values across series in each aggregation group.MetricsQL only
QueryBuilder.distinct(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
geomean()Compute the geometric mean across series in each aggregation group.MetricsQL only
QueryBuilder.geomean(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
group()Return 1 for every nonempty aggregation group.
QueryBuilder.group(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
histogram()Build a MetricsQL histogram from values across series in each group.MetricsQL only
QueryBuilder.histogram(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
limit()Apply MetricsQL's output-series limit suffix to an aggregation.MetricsQL only
QueryBuilder.limit(count: Number) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
countint | floatRequired | Integer-valued aggregation output limit in [0, 4294967295] (unsigned 32-bit); nonfinite/fractional values and bool are rejected. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
limit_ratio()Select a deterministic fraction of series. Negative ratios select the complementary subset.PromQL only
QueryBuilder.limit_ratio(ratio: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
ratioint | float | QueryBuilderRequired | Sampling ratio in [-1, 1]; a negative value requests the complement. Values outside that interval use backend handling. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
limitk()Select up to k series deterministically. Prometheus requires its experimental-functions feature.
QueryBuilder.limitk(k: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
mad()Compute the median absolute deviation across series in each aggregation group.MetricsQL only
QueryBuilder.mad(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
max()Compute the maximum across series in each aggregation group.
QueryBuilder.max(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
median()Compute the median across series in each aggregation group.MetricsQL only
QueryBuilder.median(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
min()Compute the minimum across series in each aggregation group.
QueryBuilder.min(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
mode()Compute the most frequent value across series in each aggregation group.MetricsQL only
QueryBuilder.mode(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
outliers_iqr()Keep series outside the interquartile-range outlier bounds.MetricsQL only
QueryBuilder.outliers_iqr() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
outliers_mad()Keep series outside the group median's tolerance-scaled median absolute deviation.MetricsQL only
QueryBuilder.outliers_mad(tolerance: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
toleranceint | float | QueryBuilderRequired | Multiplier applied to median absolute deviation; use a nonnegative value. Evaluated by the backend. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
outliersk()Keep up to k series with the largest deviations from their group average over the requested interval.MetricsQL only
QueryBuilder.outliersk(k: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
quantile()Compute a quantile across the series in each aggregation group.
QueryBuilder.quantile(q: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
qint | float | QueryBuilderRequired | Requested quantile, normally in [0, 1]. Out-of-range values follow backend quantile semantics; the builder does not universally reject them. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
quantiles()Compute several MetricsQL quantiles across series and identify each quantile with an output label.MetricsQL only
QueryBuilder.quantiles(label: str, *quantiles: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
labelstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
*quantilesint | float | QueryBuilder, ...Variadic | One or more requested quantiles, normally each in [0, 1]. PromQL histogram_quantiles accepts at most 10 quantiles; MetricsQL supports its own variadic form. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
stddev()Compute the population standard deviation across series in each aggregation group.
QueryBuilder.stddev(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
stdvar()Compute the population variance across series in each aggregation group.
QueryBuilder.stdvar(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
sum()Compute the sum across series in each aggregation group.
QueryBuilder.sum(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
sum2()Compute the sum of squared values across series in each aggregation group.MetricsQL only
QueryBuilder.sum2(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
topk()Keep the k largest sample values in each aggregation group, preserving the selected series labels.
QueryBuilder.topk(k: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
topk_avg()Keep k series with the largest arithmetic mean across the MetricsQL query interval, optionally collecting remaining series.MetricsQL only
QueryBuilder.topk_avg(k: ScalarInput, *, other: Optional[str]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
otherstr | NoneDefault: None | Optional 'label=value' assignment identifying the combined remainder series. None omits it. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
topk_last()Keep k series with the largest last value across the MetricsQL query interval, optionally collecting remaining series.MetricsQL only
QueryBuilder.topk_last(k: ScalarInput, *, other: Optional[str]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
otherstr | NoneDefault: None | Optional 'label=value' assignment identifying the combined remainder series. None omits it. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
topk_max()Keep k series with the largest maximum across the MetricsQL query interval, optionally collecting remaining series.MetricsQL only
QueryBuilder.topk_max(k: ScalarInput, *, other: Optional[str]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
otherstr | NoneDefault: None | Optional 'label=value' assignment identifying the combined remainder series. None omits it. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
topk_median()Keep k series with the largest median across the MetricsQL query interval, optionally collecting remaining series.MetricsQL only
QueryBuilder.topk_median(k: ScalarInput, *, other: Optional[str]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
otherstr | NoneDefault: None | Optional 'label=value' assignment identifying the combined remainder series. None omits it. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
topk_min()Keep k series with the largest minimum across the MetricsQL query interval, optionally collecting remaining series.MetricsQL only
QueryBuilder.topk_min(k: ScalarInput, *, other: Optional[str]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
kint | float | QueryBuilderRequired | Number of series to select; use a positive integer for a nonempty top/bottom selection. Scalar expressions are accepted; backend conversion and edge semantics apply. |
otherstr | NoneDefault: None | Optional 'label=value' assignment identifying the combined remainder series. None omits it. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
without()Group an ungrouped aggregation after removing these labels and the metric name. It cannot be combined with by() on the same aggregate.
QueryBuilder.without(*labels: str) -> QueryBuilder
Apply exactly one of by()/without(), once, to an ungrouped aggregation. Omitting grouping is legal in both dialects.
| Parameter / type | Meaning and accepted values |
|---|---|
*labelsstr, ...Variadic | Label names, passed separately. Grouping and matching lists must not contain duplicates. An empty grouping list is allowed; function-specific arity is checked by Rust. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
Example
from metricraft import QueryBuilder as Q
Q.from_metric("up").sum().without("instance").build(mode="promql")zscore()Compute the z-score across series in each aggregation group.MetricsQL only
QueryBuilder.zscore(*others: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*othersQueryBuilder, ...Variadic | Additional input expressions. Multiple aggregation inputs and union-style transforms are MetricsQL-only; ordinary PromQL aggregation takes just the receiver. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.