Label operations
Transform output labels without modifying source expressions.
Selector matchers choose input series. Label functions here transform or filter the result of an expression, so they can be applied after functions and aggregation.
from metricraft import QueryBuilder as Q
query = Q.from_metric("up").label_replace("host", "$1", "instance", "([^:]+):.*")
print(query.build(mode="promql"))Mapping APIs take explicit two-string tuples. Replacements use backend capture references such as $1; Python interpolation is not involved. MetricsQL-only operations are marked individually.
Methods and parameters
QueryBuilder
alias()Replace the output metric name with a literal name.MetricsQL only
QueryBuilder.alias(name: StringInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
namestrRequired | Nonempty metric/function/binding name. It is validated by the relevant constructor, not inserted as raw query syntax. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
drop_common_labels()Remove labels shared with identical values across all input series.MetricsQL only
QueryBuilder.drop_common_labels(*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.
keep_metric_names()Retain metric names through an eligible MetricsQL function or binary expression.MetricsQL only
QueryBuilder.keep_metric_names() -> QueryBuilder
No parameters.
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
label_copy()Copy source labels to destination labels in pair order; missing sources are skipped.MetricsQL only
QueryBuilder.label_copy(*pairs: Tuple[str, str]) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*pairstuple[str, str], ...Variadic | Pass each mapping as a two-string tuple, in order. label_copy/move use source and destination names; label_map uses source and destination values. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
label_del()Remove the named output labels.MetricsQL only
QueryBuilder.label_del(*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.
label_graphite_group()Construct a metric name from selected zero-based dot-separated components of its existing name.MetricsQL only
QueryBuilder.label_graphite_group(*groups: ScalarInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*groupsint, ...Variadic | Nonnegative, zero-based dot-separated metric-name component indexes. Use whole numbers; the SDK rejects bool but does not enforce integer/index bounds for this function. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
label_join()Join source label values using a separator and write the result to a destination label.
QueryBuilder.label_join(destination: StringInput, separator: StringInput, *sources: StringInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
destinationstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
separatorstrRequired | Literal separator between source label values; may be empty. |
*sourcesstr, ...Variadic | Source label names to concatenate, in the supplied order. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
label_keep()Retain only the named output labels.MetricsQL only
QueryBuilder.label_keep(*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.
label_lowercase()Convert the values of the named labels to lowercase.MetricsQL only
QueryBuilder.label_lowercase(*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.
label_map()Map exact label values through ordered source-value/destination-value pairs.MetricsQL only
QueryBuilder.label_map(label: StringInput, *pairs: Tuple[str, str]) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
labelstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
*pairstuple[str, str], ...Variadic | Pass each mapping as a two-string tuple, in order. label_copy/move use source and destination names; label_map uses source and destination values. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
label_match()Keep series whose named label matches an anchored backend regular expression.MetricsQL only
QueryBuilder.label_match(label: StringInput, regex: StringInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
labelstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
regexstrRequired | Backend RE2 pattern. Capture references in replacements use $1 or named captures. Query quoting does not make the regex literal. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
label_mismatch()Keep series whose named label does not match an anchored backend regular expression.MetricsQL only
QueryBuilder.label_mismatch(label: StringInput, regex: StringInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
labelstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
regexstrRequired | Backend RE2 pattern. Capture references in replacements use $1 or named captures. Query quoting does not make the regex literal. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
label_move()Move source labels to destinations in pair order and remove their source labels.MetricsQL only
QueryBuilder.label_move(*pairs: Tuple[str, str]) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*pairstuple[str, str], ...Variadic | Pass each mapping as a two-string tuple, in order. label_copy/move use source and destination names; label_map uses source and destination values. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
label_replace()Match one source label with a regex and write the expanded replacement to a destination label.
QueryBuilder.label_replace(destination: StringInput, replacement: StringInput, source: StringInput, regex: StringInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
destinationstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
replacementstrRequired | Replacement text with optional backend capture references such as '$1'. Encoded as a string literal. |
sourcestrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
regexstrRequired | Backend RE2 pattern. Capture references in replacements use $1 or named captures. Query quoting does not make the regex literal. |
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").label_replace("host", "$1", "instance", "([^:]+):.*").build(mode="promql")label_set()Set literal output label values without changing the input expression.MetricsQL only
QueryBuilder.label_set(**labels: StringInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
**labelsstr, by keywordVariadic | Label-name/string-value pairs, e.g. job='api'. Use **mapping for names that are not Python identifiers. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
label_transform()Replace every regex match within a label value using capture expansion.MetricsQL only
QueryBuilder.label_transform(label: StringInput, regex: StringInput, replacement: StringInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
labelstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
regexstrRequired | Backend RE2 pattern. Capture references in replacements use $1 or named captures. Query quoting does not make the regex literal. |
replacementstrRequired | Replacement text with optional backend capture references such as '$1'. Encoded as a string literal. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
label_uppercase()Convert the values of the named labels to uppercase.MetricsQL only
QueryBuilder.label_uppercase(*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.
label_value()Use a numeric label value as the sample value; unparseable values yield no samples.MetricsQL only
QueryBuilder.label_value(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.
labels_equal()Keep series whose selected label values are all equal.MetricsQL only
QueryBuilder.labels_equal(first: StringInput, second: StringInput, *others: StringInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
firststrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
secondstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
*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.