Selectors & filters
Choose metrics and attach literal label constraints.
Apply matchers before transforming a selector. Equality values are escaped; regex methods accept intentional RE2 patterns. A regex may match many values even though its query-string representation is safely quoted.
from metricraft import QueryBuilder as Q
query = (Q.from_metric("http_requests_total")
.where_eq("environment", "production")
.where_regex("status", "5.."))
print(query.build(mode="promql"))All matchers on one selector must hold. An absent label behaves as an empty value. Application code still chooses which metric names, operations and label names users may select.
Methods and parameters
QueryBuilder
filter()Keep series whose label equals a literal value; an absent label behaves like an empty string.
QueryBuilder.filter(label: str, value: Optional[StringInput]) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
labelstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
valuestrRequired | Label value or RE2 pattern for regex matchers. Encoded as a quoted query string; empty strings are allowed. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
or_selector()Combine selector alternatives inside a MetricsQL selector. This is different from the vector set operator or_().MetricsQL only
QueryBuilder.or_selector(*others: QueryBuilder) -> 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.
where()Add one label matcher to a selector. Compose filters before range, function or aggregation operations.
QueryBuilder.where(label: str, operator: Matcher, value: Optional[StringInput]) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
labelstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
operatorstrRequired | Exactly '=', '!=', '=~' or '!~'. Raw operators or query fragments are rejected. |
valuestrRequired | Label value or RE2 pattern for regex matchers. Encoded as a quoted query string; empty strings are allowed. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
where_eq()Keep series whose label equals a literal value; an absent label behaves like an empty string.
QueryBuilder.where_eq(label: str, value: Optional[StringInput]) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
labelstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
valuestrRequired | Label value or RE2 pattern for regex matchers. Encoded as a quoted query string; empty strings are allowed. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
where_ne()Keep series whose label differs from a literal value.
QueryBuilder.where_ne(label: str, value: Optional[StringInput]) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
labelstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
valuestrRequired | Label value or RE2 pattern for regex matchers. Encoded as a quoted query string; empty strings are allowed. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
where_not_regex()Add a negated fully anchored RE2 label matcher.
QueryBuilder.where_not_regex(label: str, value: Optional[StringInput]) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
labelstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
valuestrRequired | Label value or RE2 pattern for regex matchers. Encoded as a quoted query string; empty strings are allowed. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
where_regex()Add a fully anchored RE2 label matcher. The pattern is escaped as query data but remains a regular expression.
QueryBuilder.where_regex(label: str, value: Optional[StringInput]) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
labelstrRequired | Nonempty label name without control characters. The builder quotes names when required by the dialect. |
valuestrRequired | Label value or RE2 pattern for regex matchers. Encoded as a quoted query string; empty strings are allowed. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.