MetricsQL transforms
Shape complete query intervals, fill gaps and work with histogram buckets.
Unlike sliding rollups, range_* transforms summarize the entire returned MetricsQL interval. running_* transforms accumulate from the start of that interval. Their meaning depends on the range request’s start, end and step.
from metricraft import QueryBuilder as Q
query = Q.from_metric("queue_depth").keep_last_value().range_avg()
print(query.build(mode="metricsql"))These methods construct expressions. They do not load samples or execute transformations in Python. histogram_quantiles() also supports an explicit Prometheus experimental form.
Methods and parameters
QueryBuilder
bitmap_and()Apply bitwise AND to sample values and a numeric mask using MetricsQL integer conversion.MetricsQL only
QueryBuilder.bitmap_and(value: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
valueint | float | QueryBuilderRequired | Numeric scalar or scalar expression; Python bool is rejected. Computed values are evaluated by the backend. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
bitmap_or()Apply bitwise OR to sample values and a numeric mask using MetricsQL integer conversion.MetricsQL only
QueryBuilder.bitmap_or(value: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
valueint | float | QueryBuilderRequired | Numeric scalar or scalar expression; Python bool is rejected. Computed values are evaluated by the backend. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
bitmap_xor()Apply bitwise XOR to sample values and a numeric mask using MetricsQL integer conversion.MetricsQL only
QueryBuilder.bitmap_xor(value: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
valueint | float | QueryBuilderRequired | Numeric scalar or scalar expression; Python bool is rejected. Computed values are evaluated by the backend. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
buckets_limit()Reduce the number of buckets in a MetricsQL histogram.MetricsQL only
QueryBuilder.buckets_limit(value: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
valueint | float | QueryBuilderRequired | Maximum histogram bucket count; use a positive integer. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
drop_empty_series()Remove MetricsQL series with no values across the requested query interval.MetricsQL only
QueryBuilder.drop_empty_series() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
histogram_quantiles()Estimate several histogram quantiles, adding a label for the requested quantile. The builder chooses dialect-specific argument ordering.
QueryBuilder.histogram_quantiles(label: StringInput, *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.
interpolate()Fill gaps between known MetricsQL samples by linear interpolation.MetricsQL only
QueryBuilder.interpolate() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
keep_last_value()Fill gaps using the preceding known sample in a MetricsQL range query.MetricsQL only
QueryBuilder.keep_last_value() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
keep_next_value()Fill gaps using the following known sample in a MetricsQL range query.MetricsQL only
QueryBuilder.keep_next_value() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
limit_offset()Skip a number of output series and return at most the requested limit.MetricsQL only
QueryBuilder.limit_offset(limit: ScalarInput, offset: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
limitint | float | QueryBuilderRequired | Maximum number of output series; use a nonnegative integer. Backend handles computed values. |
offsetint | float | QueryBuilderRequired | Number of output series to skip; use a nonnegative integer. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
prometheus_buckets()Convert VictoriaMetrics histogram bucket labels to Prometheus le bucket labels.MetricsQL only
QueryBuilder.prometheus_buckets() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
rand()Create MetricsQL uniformly distributed random values, optionally using a seed.MetricsQL only
QueryBuilder.rand(seed: Optional[ScalarInput]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
seedint | float | QueryBuilder | NoneDefault: None | Optional scalar random seed. None uses backend default seeding; the builder does not generate random samples locally. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
rand_exponential()Create MetricsQL exponentially distributed random values, optionally using a seed.MetricsQL only
QueryBuilder.rand_exponential(seed: Optional[ScalarInput]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
seedint | float | QueryBuilder | NoneDefault: None | Optional scalar random seed. None uses backend default seeding; the builder does not generate random samples locally. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
rand_normal()Create MetricsQL normally distributed random values, optionally using a seed.MetricsQL only
QueryBuilder.rand_normal(seed: Optional[ScalarInput]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
seedint | float | QueryBuilder | NoneDefault: None | Optional scalar random seed. None uses backend default seeding; the builder does not generate random samples locally. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
range_avg()Compute the arithmetic mean across the full MetricsQL query interval, rather than a sliding lookbehind window.MetricsQL only
QueryBuilder.range_avg() -> QueryBuilder
No parameters.
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("queue_depth").range_avg().build(mode="metricsql")range_first()Compute the first value across the full MetricsQL query interval, rather than a sliding lookbehind window.MetricsQL only
QueryBuilder.range_first() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
range_last()Compute the last value across the full MetricsQL query interval, rather than a sliding lookbehind window.MetricsQL only
QueryBuilder.range_last() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
range_linear_regression()Replace a MetricsQL range-query series with its fitted regression line.MetricsQL only
QueryBuilder.range_linear_regression() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
range_mad()Compute the median absolute deviation across the full MetricsQL query interval, rather than a sliding lookbehind window.MetricsQL only
QueryBuilder.range_mad() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
range_max()Compute the maximum across the full MetricsQL query interval, rather than a sliding lookbehind window.MetricsQL only
QueryBuilder.range_max() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
range_median()Compute the median across the full MetricsQL query interval, rather than a sliding lookbehind window.MetricsQL only
QueryBuilder.range_median() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
range_min()Compute the minimum across the full MetricsQL query interval, rather than a sliding lookbehind window.MetricsQL only
QueryBuilder.range_min() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
range_normalize()Normalize MetricsQL range-query sample values using the range's minimum and maximum.MetricsQL only
QueryBuilder.range_normalize(*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.
range_quantile()Replace a MetricsQL range-query series with its quantile over the full requested interval.MetricsQL only
QueryBuilder.range_quantile(value: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
valueint | 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.
range_stddev()Compute the population standard deviation across the full MetricsQL query interval, rather than a sliding lookbehind window.MetricsQL only
QueryBuilder.range_stddev() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
range_stdvar()Compute the population variance across the full MetricsQL query interval, rather than a sliding lookbehind window.MetricsQL only
QueryBuilder.range_stdvar() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
range_sum()Compute the sum across the full MetricsQL query interval, rather than a sliding lookbehind window.MetricsQL only
QueryBuilder.range_sum() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
range_trim_outliers()Remove samples whose distance from the interval median exceeds a scaled median absolute deviation.MetricsQL only
QueryBuilder.range_trim_outliers(value: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
valueint | 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.
range_trim_spikes()Remove the requested fraction of upper and lower extreme samples across the query interval.MetricsQL only
QueryBuilder.range_trim_spikes(value: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
valueint | float | QueryBuilderRequired | Fraction of extreme samples to trim, normally in [0, 1]. Evaluated by the backend. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
range_trim_zscore()Remove samples whose absolute z-score exceeds the supplied threshold.MetricsQL only
QueryBuilder.range_trim_zscore(value: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
valueint | float | QueryBuilderRequired | Nonnegative absolute z-score threshold, such as 3. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
range_zscore()Compute the z-score across the full MetricsQL query interval, rather than a sliding lookbehind window.MetricsQL only
QueryBuilder.range_zscore() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
remove_resets()Adjust a counter sequence to remove downward reset discontinuities.MetricsQL only
QueryBuilder.remove_resets() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
ru()Compute MetricsQL resource utilization as a percentage from the receiver's free capacity and the supplied maximum capacity.MetricsQL only
QueryBuilder.ru(value: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
valueint | float | QueryBuilderRequired | Positive maximum resource capacity used as the utilization denominator. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
running_avg()Compute the running arithmetic mean from the start of a MetricsQL range query up to each evaluation point.MetricsQL only
QueryBuilder.running_avg() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
running_max()Compute the running maximum from the start of a MetricsQL range query up to each evaluation point.MetricsQL only
QueryBuilder.running_max() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
running_min()Compute the running minimum from the start of a MetricsQL range query up to each evaluation point.MetricsQL only
QueryBuilder.running_min() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
running_sum()Compute the running sum from the start of a MetricsQL range query up to each evaluation point.MetricsQL only
QueryBuilder.running_sum() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
timezone_offset()Create a scalar giving a named timezone's UTC offset in seconds at evaluation time.MetricsQL only
QueryBuilder.timezone_offset(timezone: StringInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
timezonestrRequired | IANA timezone name such as 'Europe/Paris' or 'UTC'. Existence is checked by the backend timezone database. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
ttf()Estimate time to failure (time until zero) from a decreasing gauge.MetricsQL only
QueryBuilder.ttf() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.