MetricsQL templates
Define scoped immutable values and reusable expression templates.
Bindings are local to a query. No global symbol registry or raw string substitution is used. References must resolve and their declared result types must agree with the binding.
from metricraft import QueryBuilder as Q
query = Q.reference("base").sum().with_(base=Q.from_metric("up"))
print(query.build(mode="metricsql"))Bindings follow keyword insertion order: earlier bindings are visible to later ones. Duplicate/invalid parameter names, unresolved references and recursion are rejected.
Methods and parameters
QueryBuilder
reference()Create a typed name reference that must resolve inside a MetricsQL WITH binding or template parameter scope.MetricsQL only
QueryBuilder.reference(name: str, *, kind: ReferenceKind='instant') -> 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. |
kindstrDefault: 'instant' | Declared reference result kind: 'instant', 'range', 'scalar', or 'string'. The resolved binding must match. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
template()Define a MetricsQL function template with explicit parameters and an immutable expression body.MetricsQL only
QueryBuilder.template(*parameters: str, body: QueryInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
*parametersstr, ...Variadic | Unique valid MetricsQL identifiers for template parameters. They are scoped to the template body. |
bodyQueryBuilder | int | float | strRequired | Template expression body; strings become literal values, not source code. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
template_call()Call a named template in the enclosing MetricsQL scope.MetricsQL only
QueryBuilder.template_call(name: str, *args: QueryInput, kind: ReferenceKind='instant') -> 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. |
*argsQueryBuilder | int | float | str, ...Variadic | Typed function arguments in upstream order. Strings become literals; numeric/vector/range types and arity are checked by Rust. |
kindstrDefault: 'instant' | Declared reference result kind: 'instant', 'range', 'scalar', or 'string'. The resolved binding must match. |
Returns QueryBuilder — a new immutable expression sharing unchanged native subtrees. The receiver is unchanged; no data is queried.
with_()Add local MetricsQL value/function bindings in insertion order. Earlier bindings are visible to later ones.MetricsQL only
QueryBuilder.with_(**bindings: QueryInput) -> QueryBuilder
| Parameter / type | Meaning and accepted values |
|---|---|
**bindingsQueryBuilder | int | float | str, by keywordVariadic | Binding-name/value pairs in insertion order. Identifiers must be valid, scope must resolve, and recursive definitions are rejected. |
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.reference("base").sum().with_(base=Q.from_metric("up")).build(mode="metricsql")