Operators & matching
Compose arithmetic, comparisons and vector matching.
Python operators construct immutable query expressions. Comparisons do not return Python booleans, and none of these operations modifies its operands.
| Python | Query operation | Named alternative |
|---|---|---|
a + b, a - b, a * b, a / b | Arithmetic | .add(), .sub(), .mul(), .div() |
a % b, a ** b | Remainder, exponentiation (^ in PromQL) | .mod(), .pow() |
-a, +a | Unary sign | .negative(), .positive() |
a > b, a >= b, a < b, a <= b | Filtering comparison | .gt(), .ge(), .lt(), .le() |
a == b, a != b | Filtering equality/inequality | .eq(), .ne() |
a & b, a | b | Vector set intersection/union | .and_(), .or_() |
A scalar can appear on either side of +, -, * and /. Reverse % and
** are not overloaded; write Q.from_scalar(value) explicitly on the left
when you need those forms. Python ^ is not the power operator: use **.
from metricraft import QueryBuilder as Q
errors = Q.from_metric("errors_total").rate("5m")
requests = Q.from_metric("requests_total").rate("5m")
fraction = (errors / requests).on("service")
query = (fraction * 100) > 1
print(query.build(mode="promql"))Attach matching/grouping modifiers to the binary expression. A comparison filters samples unless .bool() requests 0/1 values. Python and, or, not and if expression reject query expressions. Use (a > 1) & (b < 5) with explicit parentheses instead of chained comparisons or Python boolean operators.
Methods and parameters
QueryBuilder
add()Add the right operand, using native scalar/vector type and matching checks.
QueryBuilder.add(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.
and_()Keep left-hand series with a matching right-hand series. Values come from the left.
QueryBuilder.and_(other: ScalarInput) -> 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.
atan2()Compute a two-argument arctangent with scalar/vector matching rules.
QueryBuilder.atan2(other: ScalarInput) -> 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.
between()Keep vector samples inside inclusive literal numeric bounds.
QueryBuilder.between(minimum: Number, maximum: Number) -> 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.
bool()Make a comparison return 0 or 1 instead of filtering false samples. Apply to a comparison expression.
QueryBuilder.bool() -> 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("up").eq(1).bool().build(mode="promql")default()Fill gaps in the left MetricsQL expression using matching values from the right expression.MetricsQL only
QueryBuilder.default(other: ScalarInput) -> 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.
div()Divide by the right operand, using native scalar/vector type and matching checks.
QueryBuilder.div(other: ScalarInput) -> 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.
eq()Compare with the right operand: equal to. Vector comparisons filter by default; append bool() for 0/1 results.
QueryBuilder.eq(other: ScalarInput) -> 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.
eq_any()Compare against a MetricsQL scalar tuple, retaining values equal to any member.MetricsQL only
QueryBuilder.eq_any(*values: QueryInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*valuesint | float | str | QueryBuilder, ...Variadic | Nonempty uniformly scalar or uniformly string tuple. Comparison tuples must have the appropriate numeric type. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
fill()Set a missing-match fill value for both sides of an eligible Prometheus binary operation.PromQL only
QueryBuilder.fill(value: Number) -> QueryBuilder
Requires features=('promql-binop-fill-modifiers',) and matching server support.
| 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.
fill_left()Set a missing-match fill value for the left side of an eligible Prometheus binary operation.PromQL only
QueryBuilder.fill_left(value: Number) -> QueryBuilder
Requires features=('promql-binop-fill-modifiers',) and matching server support.
| 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.
fill_right()Set a missing-match fill value for the right side of an eligible Prometheus binary operation.PromQL only
QueryBuilder.fill_right(value: Number) -> QueryBuilder
Requires features=('promql-binop-fill-modifiers',) and matching server support.
| 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.
ge()Compare with the right operand: greater than or equal to. Vector comparisons filter by default; append bool() for 0/1 results.
QueryBuilder.ge(other: ScalarInput) -> 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.
group_left()Enable many-to-one vector matching, optionally copying labels from the one-side (right).
QueryBuilder.group_left(*labels: str) -> 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.
group_left_all()Copy all eligible labels from the right side of a MetricsQL many-to-one match, optionally adding a prefix.MetricsQL only
QueryBuilder.group_left_all(*, prefix: str='') -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
prefixstrDefault: '' | Literal prefix for copied labels; empty means no prefix. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
group_right()Enable one-to-many vector matching, optionally copying labels from the one-side (left).
QueryBuilder.group_right(*labels: str) -> 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.
group_right_all()Copy all eligible labels from the left side of a MetricsQL one-to-many match, optionally adding a prefix.MetricsQL only
QueryBuilder.group_right_all(*, prefix: str='') -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
prefixstrDefault: '' | Literal prefix for copied labels; empty means no prefix. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
gt()Compare with the right operand: greater than. Vector comparisons filter by default; append bool() for 0/1 results.
QueryBuilder.gt(other: ScalarInput) -> 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.
if_()Keep left-hand MetricsQL samples only where matching right-hand samples exist.MetricsQL only
QueryBuilder.if_(other: ScalarInput) -> 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.
ifnot()Keep left-hand MetricsQL samples only where matching right-hand samples are absent.MetricsQL only
QueryBuilder.ifnot(other: ScalarInput) -> 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.
ignoring()Match vector operands while ignoring the specified labels. Cannot be combined with on().
QueryBuilder.ignoring(*labels: str) -> 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.
le()Compare with the right operand: less than or equal to. Vector comparisons filter by default; append bool() for 0/1 results.
QueryBuilder.le(other: ScalarInput) -> 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.
lt()Compare with the right operand: less than. Vector comparisons filter by default; append bool() for 0/1 results.
QueryBuilder.lt(other: ScalarInput) -> 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.
mod()Take the remainder after division by the right operand, using native scalar/vector type and matching checks.
QueryBuilder.mod(other: ScalarInput) -> 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.
mul()Multiply by the right operand, using native scalar/vector type and matching checks.
QueryBuilder.mul(other: ScalarInput) -> 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.
ne()Compare with the right operand: not equal to. Vector comparisons filter by default; append bool() for 0/1 results.
QueryBuilder.ne(other: ScalarInput) -> 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.
ne_all()Compare against a MetricsQL scalar tuple, retaining values unequal to every member.MetricsQL only
QueryBuilder.ne_all(*values: QueryInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*valuesint | float | str | QueryBuilder, ...Variadic | Nonempty uniformly scalar or uniformly string tuple. Comparison tuples must have the appropriate numeric type. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
negative()Negate a numeric expression.
QueryBuilder.negative() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
on()Match vector operands using only the specified labels. Apply to an eligible binary expression.
QueryBuilder.on(*labels: str) -> 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.
Example
from metricraft import QueryBuilder as Q
(Q.from_metric("errors_total") / Q.from_metric("requests_total")).on("job").build(mode="promql")or_()Union two vectors, preferring left-hand series where label sets match.
QueryBuilder.or_(other: ScalarInput) -> 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.
parenthesize()Wrap the expression in explicit parentheses without changing its value.
QueryBuilder.parenthesize() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
positive()Apply unary plus to a numeric expression.
QueryBuilder.positive() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
pow()Raise to the power of the right operand, using native scalar/vector type and matching checks.
QueryBuilder.pow(other: ScalarInput) -> 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.
sub()Subtract the right operand, using native scalar/vector type and matching checks.
QueryBuilder.sub(other: ScalarInput) -> 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.
trim_lower()Remove observations below a threshold from Prometheus native histograms, interpolating a boundary bucket when needed.PromQL only
QueryBuilder.trim_lower(threshold: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
thresholdint | float | QueryBuilderRequired | Numeric histogram observation cutoff; vector thresholds use matching rules. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
trim_upper()Remove observations above a threshold from Prometheus native histograms, interpolating a boundary bucket when needed.PromQL only
QueryBuilder.trim_upper(threshold: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
thresholdint | float | QueryBuilderRequired | Numeric histogram observation cutoff; vector thresholds use matching rules. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
union()Combine MetricsQL vectors using the union function.MetricsQL only
QueryBuilder.union(*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.
unless()Keep left-hand series with no matching right-hand series.
QueryBuilder.unless(other: ScalarInput) -> 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.