Math, sorting & histograms
Transform values, extract calendar fields and estimate histogram statistics.
These methods usually consume instant vectors. Functions such as scalar() change the query value type; Rust checks whether subsequent composition is legal.
from metricraft import QueryBuilder as Q
buckets = Q.from_metric("request_duration_seconds_bucket").rate("5m")
query = buckets.sum().by("le").histogram_quantile(0.95)
print(query.build(mode="promql"))Calendar functions interpret sample values as Unix timestamps in UTC. They do not automatically read sample timestamps: use .timestamp() when that is what you want. Histogram encoding and native-histogram support depend on the backend.
Methods and parameters
QueryBuilder
abs()Replace each sample by its absolute value.
QueryBuilder.abs() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
absent()Produce a single value of 1 when the input instant vector is empty; otherwise produce no series.
QueryBuilder.absent() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
acos()Compute the inverse cosine of each sample. Angular inputs and outputs use radians; out-of-domain inputs follow backend floating-point semantics.
QueryBuilder.acos() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
acosh()Compute the inverse hyperbolic cosine of each sample. Angular inputs and outputs use radians; out-of-domain inputs follow backend floating-point semantics.
QueryBuilder.acosh() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
asin()Compute the inverse sine of each sample. Angular inputs and outputs use radians; out-of-domain inputs follow backend floating-point semantics.
QueryBuilder.asin() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
asinh()Compute the inverse hyperbolic sine of each sample. Angular inputs and outputs use radians; out-of-domain inputs follow backend floating-point semantics.
QueryBuilder.asinh() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
atan()Compute the inverse tangent of each sample. Angular inputs and outputs use radians; out-of-domain inputs follow backend floating-point semantics.
QueryBuilder.atan() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
atanh()Compute the inverse hyperbolic tangent of each sample. Angular inputs and outputs use radians; out-of-domain inputs follow backend floating-point semantics.
QueryBuilder.atanh() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
ceil()Round each sample upward to an integer.
QueryBuilder.ceil() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
clamp()Constrain sample values to inclusive lower and upper bounds.
QueryBuilder.clamp(minimum: ScalarInput, maximum: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
minimumint | float | QueryBuilderRequired | Inclusive lower sample-value bound. Use a value no greater than maximum; between() requires literal numbers. |
maximumint | float | QueryBuilderRequired | Inclusive upper sample-value bound. Use a value no less than minimum; between() requires literal numbers. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
clamp_max()Replace samples above the upper bound by that bound.
QueryBuilder.clamp_max(maximum: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
maximumint | float | QueryBuilderRequired | Inclusive upper sample-value bound. Use a value no less than minimum; between() requires literal numbers. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
clamp_min()Replace samples below the lower bound by that bound.
QueryBuilder.clamp_min(minimum: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
minimumint | float | QueryBuilderRequired | Inclusive lower sample-value bound. Use a value no greater than maximum; between() requires literal numbers. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
cos()Compute the cosine of each sample. Angular inputs and outputs use radians; out-of-domain inputs follow backend floating-point semantics.
QueryBuilder.cos() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
cosh()Compute the hyperbolic cosine of each sample. Angular inputs and outputs use radians; out-of-domain inputs follow backend floating-point semantics.
QueryBuilder.cosh() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
day_of_month()Interpret input sample values as Unix seconds and return the UTC day of the month (1–31).
QueryBuilder.day_of_month() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
day_of_week()Interpret input sample values as Unix seconds and return the UTC day of the week (0=Sunday, 6=Saturday).
QueryBuilder.day_of_week() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
day_of_year()Interpret input sample values as Unix seconds and return the UTC day of the year (1–366).
QueryBuilder.day_of_year() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
days_in_month()Interpret input sample values as Unix seconds and return the UTC number of days in the month (28–31).
QueryBuilder.days_in_month() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
deg()Convert sample values from radians to degrees.
QueryBuilder.deg() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
exp()Compute e raised to each sample value.
QueryBuilder.exp() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
floor()Round each sample downward to an integer.
QueryBuilder.floor() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
histogram_avg()Extract or estimate the histogram's arithmetic mean. Supported histogram encodings depend on the backend.
QueryBuilder.histogram_avg() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
histogram_count()Extract or estimate the histogram's count. Supported histogram encodings depend on the backend.PromQL only
QueryBuilder.histogram_count() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
histogram_fraction()Estimate the fraction of histogram observations between lower and upper bounds.
QueryBuilder.histogram_fraction(lower: ScalarInput, upper: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
lowerint | float | QueryBuilderRequired | Lower histogram observation boundary; use a value below upper, optionally negative infinity. |
upperint | float | QueryBuilderRequired | Upper histogram observation boundary; use a value above lower, optionally positive infinity. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
histogram_quantile()Estimate one quantile from classic histogram buckets or supported native histograms.
QueryBuilder.histogram_quantile(q: ScalarInput, *, bounds_label: Optional[StringInput]=None) -> QueryBuilder
For classic Prometheus buckets retain the le label through aggregation. Native histogram support and interpolation belong to the backend.
| 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. |
bounds_labelstr | NoneDefault: None | Optional output label for lower/upper estimation bounds. Supplying it selects a MetricsQL-only argument form. |
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("request_duration_seconds_bucket").rate("5m").sum().by("le").histogram_quantile(0.95).build(mode="promql")histogram_stddev()Extract or estimate the histogram's population standard deviation. Supported histogram encodings depend on the backend.
QueryBuilder.histogram_stddev() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
histogram_stdvar()Extract or estimate the histogram's population variance. Supported histogram encodings depend on the backend.
QueryBuilder.histogram_stdvar() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
histogram_sum()Extract or estimate the histogram's sum. Supported histogram encodings depend on the backend.PromQL only
QueryBuilder.histogram_sum() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
hour()Interpret input sample values as Unix seconds and return the UTC hour (0–23).
QueryBuilder.hour() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
info()Enrich a vector with data labels from matching info series. The optional selector restricts info labels.PromQL only
QueryBuilder.info(data_labels: Optional[QueryBuilder]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
data_labelsQueryBuilder | NoneDefault: None | Optional unnamed label selector from Q.from_labels(); a named metric selector is rejected for info's second argument. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
ln()Take the natural logarithm of each sample.
QueryBuilder.ln() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
log10()Take the base-10 logarithm of each sample.
QueryBuilder.log10() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
log2()Take the base-2 logarithm of each sample.
QueryBuilder.log2() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
max_of()Return the larger of two scalar expressions. This is a Prometheus experimental function.PromQL only
QueryBuilder.max_of(other: QueryInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
otherint | float | QueryBuilderRequired | Right operand. Set operators and vector matching require vector expressions; arithmetic/comparisons also accept numbers. Python bool is rejected. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
min_of()Return the smaller of two scalar expressions. This is a Prometheus experimental function.PromQL only
QueryBuilder.min_of(other: QueryInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
otherint | float | QueryBuilderRequired | Right operand. Set operators and vector matching require vector expressions; arithmetic/comparisons also accept numbers. Python bool is rejected. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
minute()Interpret input sample values as Unix seconds and return the UTC minute (0–59).
QueryBuilder.minute() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
month()Interpret input sample values as Unix seconds and return the UTC month (1–12).
QueryBuilder.month() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
rad()Convert sample values from degrees to radians.
QueryBuilder.rad() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
round()Round samples to the nearest multiple, defaulting to 1. Ties round upward.
QueryBuilder.round(nearest: Optional[ScalarInput]=None, *, to_nearest: Optional[ScalarInput]=None) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
nearestint | float | QueryBuilder | NoneDefault: None | Rounding multiple; None uses 1. Use a positive nonzero multiple. Do not also pass to_nearest. |
to_nearestint | float | QueryBuilder | NoneDefault: None | Alias of nearest; do not supply both. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
scalar()Convert a one-element instant vector to a scalar; other vector sizes yield NaN.
QueryBuilder.scalar() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
sgn()Map negative, zero and positive values to -1, 0 and 1 respectively.
QueryBuilder.sgn() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
sin()Compute the sine of each sample. Angular inputs and outputs use radians; out-of-domain inputs follow backend floating-point semantics.
QueryBuilder.sin() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
sinh()Compute the hyperbolic sine of each sample. Angular inputs and outputs use radians; out-of-domain inputs follow backend floating-point semantics.
QueryBuilder.sinh() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
smooth_exponential()Apply exponential smoothing to the sequence of values returned by a MetricsQL range query.MetricsQL only
QueryBuilder.smooth_exponential(smoothing_factor: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
smoothing_factorint | float | QueryBuilderRequired | Smoothing factor in the inclusive interval [0, 1]. Literal factors outside this range are rejected by Rust. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
sort()Sort an instant-query result by value in the selected direction.
QueryBuilder.sort(direction: Literal['asc', 'desc']='asc') -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
directionstrDefault: 'asc' | Either 'asc' or 'desc'. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
sort_by_label()Order series by the specified label values, using natural label ordering, ascending.
QueryBuilder.sort_by_label(*labels: StringInput) -> QueryBuilder
| 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.
sort_by_label_desc()Order series by the specified label values, using natural label ordering, descending.
QueryBuilder.sort_by_label_desc(*labels: StringInput) -> QueryBuilder
| 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.
sort_by_label_numeric()Order series by the specified label values, numerically, ascending.MetricsQL only
QueryBuilder.sort_by_label_numeric(*labels: StringInput) -> QueryBuilder
| 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.
sort_by_label_numeric_desc()Order series by the specified label values, numerically, descending.MetricsQL only
QueryBuilder.sort_by_label_numeric_desc(*labels: StringInput) -> QueryBuilder
| 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.
sort_desc()Sort an instant-query result by value from largest to smallest.
QueryBuilder.sort_desc() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
sqrt()Take the square root of each sample; negative inputs produce NaN on the backend.
QueryBuilder.sqrt() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
tan()Compute the tangent of each sample. Angular inputs and outputs use radians; out-of-domain inputs follow backend floating-point semantics.
QueryBuilder.tan() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
tanh()Compute the hyperbolic tangent of each sample. Angular inputs and outputs use radians; out-of-domain inputs follow backend floating-point semantics.
QueryBuilder.tanh() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
timestamp()Replace sample values with their source timestamps in Unix seconds.
QueryBuilder.timestamp() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
year()Interpret input sample values as Unix seconds and return the UTC calendar year.
QueryBuilder.year() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.