模板与作用域 · MetriCraft

绑定仅在当前查询中有效，不使用全局符号注册表或原始字符串替换。引用必须能够解析，声明的结果类型也必须与绑定一致。

from metricraft import QueryBuilder as Q

query = Q.reference("base").sum().with_(base=Q.from_metric("up"))
print(query.build(mode="metricsql"))

绑定遵循关键字插入顺序：更早的绑定对后面的绑定可见。重复或无效的参数名、未解析引用及递归会被拒绝。

方法与参数

在本页查找

reference()创建有类型的名称引用，必须在 MetricsQL WITH 绑定或模板参数作用域内解析。仅限 MetricsQL

类方法仅限 MetricsQL

QueryBuilder.reference(name: str, *, kind: ReferenceKind='instant') -> QueryBuilder

参数
参数 / 类型	含义与可接受的值
`name`str必填	非空指标、函数或绑定名称，由对应构造函数验证，不作为原始查询语法插入。
`kind`str默认值： 'instant'	声明的引用结果类型：'instant'、'range'、'scalar' 或 'string'。解析后的绑定必须匹配。

返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。

template()用显式参数和不可变表达式主体定义 MetricsQL 函数模板。仅限 MetricsQL

类方法仅限 MetricsQL

QueryBuilder.template(*parameters: str, body: QueryInput) -> QueryBuilder

参数
参数 / 类型	含义与可接受的值
`*parameters`str, ...可变参数	唯一且有效的 MetricsQL 模板参数标识符，作用域限定为模板主体。
`body`QueryBuilder \| int \| float \| str必填	模板表达式主体。字符串变成字面量值，不是源码。

返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。

template_call()调用外围 MetricsQL 作用域内的命名模板。仅限 MetricsQL

类方法仅限 MetricsQL

QueryBuilder.template_call(name: str, *args: QueryInput, kind: ReferenceKind='instant') -> QueryBuilder

参数
参数 / 类型	含义与可接受的值
`name`str必填	非空指标、函数或绑定名称，由对应构造函数验证，不作为原始查询语法插入。
`*args`QueryBuilder \| int \| float \| str, ...可变参数	按上游顺序提供有类型的函数参数。字符串变成字面量，数字、向量、范围类型及参数个数由 Rust 检查。
`kind`str默认值： 'instant'	声明的引用结果类型：'instant'、'range'、'scalar' 或 'string'。解析后的绑定必须匹配。

返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。

with_()按插入顺序添加局部 MetricsQL 值或函数绑定，后续绑定可见前面的绑定。仅限 MetricsQL

仅限 MetricsQL

QueryBuilder.with_(**bindings: QueryInput) -> QueryBuilder

参数
参数 / 类型	含义与可接受的值
`**bindings`QueryBuilder \| int \| float \| str, 按关键字传入可变参数	按插入顺序提供绑定名和值。标识符必须有效，作用域内引用必须可解析，不允许递归定义。

返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。

from metricraft import QueryBuilder as Q

Q.reference("base").sum().with_(base=Q.from_metric("up")).build(mode="metricsql")