参考手册
创建表达式
从指标、标签、标量、字符串和函数调用开始构建。
表达式从工厂方法开始。导入 QueryBuilder as Q；传给 function() 的 Python 字符串始终是字面量，不会被解析为查询。构建返回文本，不执行 I/O。
from metricraft import QueryBuilder as Q
base = Q.from_metric("http_requests_total").where_eq("job", "api")
query = base.rate("5m").sum().by("job")
print(query.build(mode="promql"))默认方言为 MetricsQL，面向 Prometheus 时请显式选择 PromQL。类型检查可能发生在构建表达式时；方言和输出预算还会在最终构建时检查完整表达式。TypeError 表示 Python 输入不兼容，ValueError 表示原生构建或输出约束不满足。
方法与参数
QueryBuilder
QueryBuilder()创建无状态工厂。建议使用类级 from_* 工厂方法开始一个表达式。
build()按所选方言验证整个表达式并渲染查询文本，不发送请求或计算数据。
QueryBuilder.build(mode: BuildMode=QueryMode.METRICSQL, *, max_output_bytes: Optional[int]=None, max_expanded_nodes: Optional[int]=None, experimental_functions: bool=False, features: Iterable[str]=()) -> str
| 参数 / 类型 | 含义与可接受的值 |
|---|---|
modeQueryMode | str默认值： QueryMode.METRICSQL | 'promql' 或默认的 'metricsql'。检查完整表达式，包括方言专属参数形式。 |
max_output_bytesint | None默认值： None | 正整数字节预算。None 使用原生默认值 1 MiB，拒绝 bool 和零。按 UTF-8 字节而不是字符数计量。 |
max_expanded_nodesint | None默认值： None | 正整数表达式出现次数预算。None 使用 100,000；即使底层存储共享，每次渲染重复引用都计数。 |
experimental_functionsbool默认值： False | 启用 Prometheus 实验函数。后端也必须启用对应功能，此开关不配置服务器。 |
featuresIterable[str]默认值： () | 显式功能名：'promql-experimental-functions'、'promql-duration-expr'、'promql-extended-range-selectors'、'promql-binop-fill-modifiers'。各项都需要对应服务器支持。请传集合，不要传单个字符串。 |
返回值 str：已验证的查询文本，可保存或用于客户端请求。
示例
from metricraft import QueryBuilder as Q
Q.from_metric("up").build(mode="promql", max_output_bytes=4096)from_duration()创建有类型的标量时长，渲染为秒。MetricsQL 中相对步长的单位仍是查询时表达式。
from_labels()从等值匹配器创建无指标名选择器。PromQL 中至少一个匹配器必须排除空标签值。
类方法
QueryBuilder.from_labels(**labels: str) -> QueryBuilder
| 参数 / 类型 | 含义与可接受的值 |
|---|---|
**labelsstr, 按关键字传入可变参数 | 标签名和字符串值组成的关键字对，如 job='api'。名称不是 Python 标识符时使用 **mapping。 |
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。
示例
from metricraft import QueryBuilder as Q Q.from_labels(job="api").build(mode="promql")
from_metric()为指标创建即时向量选择器。名称作为数据编码，必要时加引号。
from_numeric_literal()解析并规范化数字表示，包括 MetricsQL 的 SI 和二进制后缀；拒绝任意查询文本。
类方法
QueryBuilder.from_numeric_literal(value: str) -> QueryBuilder
| 参数 / 类型 | 含义与可接受的值 |
|---|---|
valuestr必填 | 数字表示，如 '1.25'、'2K' 或 '4Mi'。支持 K/M/G/T 与 Ki/Mi/Gi/Ti 后缀，区分大小写；移除下划线。值规范化为普通标量，可用于两种方言。拒绝多余查询词法元素及后缀溢出。 |
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。
示例
from metricraft import QueryBuilder as Q
Q.from_numeric_literal("2K").build(mode="promql")from_scalar()创建标量数字字面量。即使 bool 继承 int，也会拒绝 Python 布尔值。
类方法
QueryBuilder.from_scalar(value: Number) -> QueryBuilder
原生标量使用 f64，超出 IEEE-754 精确整数范围的 Python 整数可能被舍入。
| 参数 / 类型 | 含义与可接受的值 |
|---|---|
valueint | float必填 | 数字字面量，包括 IEEE NaN 和无穷。拒绝 bool，值使用原生浮点表示。 |
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。
示例
from metricraft import QueryBuilder as Q Q.from_scalar(42).build(mode="promql")
from_string()创建经过转义的字符串字面量，用于函数参数；不会把字符串解析为查询。
from_tuple()创建非空 MetricsQL 元组，其中表达式必须全为标量或全为字符串。
function()使用有类型的参数调用 Rust 签名目录中的函数，拒绝未知函数和不兼容参数类型。
类方法
QueryBuilder.function(name: str, *args: QueryInput) -> QueryBuilder
字符串是字面量。表达式请用 Q.from_metric('up')；function('rate', 'up[5m]') 不会把参数解析为查询。
| 参数 / 类型 | 含义与可接受的值 |
|---|---|
namestr必填 | 非空指标、函数或绑定名称，由对应构造函数验证，不作为原始查询语法插入。 |
*argsQueryBuilder | int | float | str, ...可变参数 | 按上游顺序提供有类型的函数参数。字符串变成字面量，数字、向量、范围类型及参数个数由 Rust 检查。 |
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。
示例
from metricraft import QueryBuilder as Q
Q.function("rate", Q.from_metric("requests_total").range("5m")).build(mode="promql")