参考手册
选择器与过滤
通过标签匹配器选择时间序列，并组合 MetricsQL 选择器分支。
应在转换选择器之前添加匹配器。等值匹配会转义值，正则方法接受有意提供的 RE2 模式。即使查询中的字符串已经安全引用，正则仍可能匹配大量值。
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"))
同一个选择器的所有匹配器必须同时满足。不存在的标签按空值处理。应用代码仍需决定用户可选择的指标名、操作和标签名。
方法与参数
QueryBuilder
filter()保留标签等于指定字面量的序列；缺失标签按空字符串处理。
QueryBuilder.filter(label: str, value: Optional[StringInput]) -> QueryBuilder
参数| 参数 / 类型 | 含义与可接受的值 |
|---|
labelstr必填 | 不含控制字符的非空标签名。方言要求时，构建器会为名称加引号。 |
|---|
valuestr必填 | 标签值，正则匹配器中则为 RE2 模式。编码为带引号的查询字符串，允许空字符串。 |
|---|
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。
or_selector()在 MetricsQL 选择器内组合多个分支，与向量集合运算 or_() 不同。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.or_selector(*others: QueryBuilder) -> QueryBuilder
参数| 参数 / 类型 | 含义与可接受的值 |
|---|
*othersQueryBuilder, ...可变参数 | 额外输入表达式。多个聚合输入和 union 类转换仅限 MetricsQL；普通 PromQL 聚合只接收当前表达式。 |
|---|
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。
where()为选择器添加一个标签匹配器。应在范围、函数或聚合操作前组合过滤条件。
QueryBuilder.where(label: str, operator: Matcher, value: Optional[StringInput]) -> QueryBuilder
参数| 参数 / 类型 | 含义与可接受的值 |
|---|
labelstr必填 | 不含控制字符的非空标签名。方言要求时，构建器会为名称加引号。 |
|---|
operatorstr必填 | 只能是 '='、'!='、'=~' 或 '!~'。拒绝原始运算符片段或查询片段。 |
|---|
valuestr必填 | 标签值，正则匹配器中则为 RE2 模式。编码为带引号的查询字符串，允许空字符串。 |
|---|
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。
where_eq()保留标签等于指定字面量的序列；缺失标签按空字符串处理。
QueryBuilder.where_eq(label: str, value: Optional[StringInput]) -> QueryBuilder
参数| 参数 / 类型 | 含义与可接受的值 |
|---|
labelstr必填 | 不含控制字符的非空标签名。方言要求时，构建器会为名称加引号。 |
|---|
valuestr必填 | 标签值，正则匹配器中则为 RE2 模式。编码为带引号的查询字符串，允许空字符串。 |
|---|
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。
where_ne()保留标签不等于指定字面量的序列。
QueryBuilder.where_ne(label: str, value: Optional[StringInput]) -> QueryBuilder
参数| 参数 / 类型 | 含义与可接受的值 |
|---|
labelstr必填 | 不含控制字符的非空标签名。方言要求时，构建器会为名称加引号。 |
|---|
valuestr必填 | 标签值，正则匹配器中则为 RE2 模式。编码为带引号的查询字符串，允许空字符串。 |
|---|
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。
where_not_regex()添加匹配整个标签值的反向 RE2 匹配器。
QueryBuilder.where_not_regex(label: str, value: Optional[StringInput]) -> QueryBuilder
参数| 参数 / 类型 | 含义与可接受的值 |
|---|
labelstr必填 | 不含控制字符的非空标签名。方言要求时，构建器会为名称加引号。 |
|---|
valuestr必填 | 标签值，正则匹配器中则为 RE2 模式。编码为带引号的查询字符串，允许空字符串。 |
|---|
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。
where_regex()添加匹配整个标签值的 RE2 匹配器。模式作为查询数据转义，但仍保留正则语义。
QueryBuilder.where_regex(label: str, value: Optional[StringInput]) -> QueryBuilder
参数| 参数 / 类型 | 含义与可接受的值 |
|---|
labelstr必填 | 不含控制字符的非空标签名。方言要求时，构建器会为名称加引号。 |
|---|
valuestr必填 | 标签值，正则匹配器中则为 RE2 模式。编码为带引号的查询字符串，允许空字符串。 |
|---|
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。