MetriCraft/文档
EnglishGitHub
参考手册

运算符与匹配

组合算术、比较和集合运算，并设置向量匹配规则。

Python 运算符构建不可变查询表达式。比较操作不返回 Python 布尔值，这些操作都不会修改操作数。

Python查询操作命名方法
a + b, a - b, a * b, a / b算术.add(), .sub(), .mul(), .div()
a % b, a ** b余数、乘方（PromQL 中为 ^）.mod(), .pow()
-a, +a一元符号.negative(), .positive()
a > b, a >= b, a < b, a <= b过滤式比较.gt(), .ge(), .lt(), .le()
a == b, a != b相等或不等过滤.eq(), .ne()
a & b, a | b向量集合交集或并集.and_(), .or_()

标量可以放在 +、-、*、/ 任意一侧。SDK 没有重载反向 % 与 **；需要这些形式时，在左侧显式写 Q.from_scalar(value)。Python 的 ^ 不是乘方运算符，请使用 **。

from metricraft import QueryBuilder as Q

errors = Q.from_metric("errors_total").rate("5m")
requests = Q.from_metric("requests_total").rate("5m")
fraction = (errors / requests).on("service")
query = (fraction * 100) > 1
print(query.build(mode="promql"))

匹配与分组修饰符应加在二元表达式上。比较默认过滤样本，调用 .bool() 才会请求 0/1 结果。Python 的 and、or、not、if expression 会拒绝查询表达式。请使用显式括号，例如 (a > 1) & (b < 5)，不要使用链式比较或 Python 布尔运算符。

方法与参数

QueryBuilder

add()加上右操作数，并使用原生标量/向量类型与匹配校验。
QueryBuilder.add(other: QueryInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
and_()保留能匹配右侧序列的左侧序列，值来自左侧。
QueryBuilder.and_(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
atan2()按标量与向量匹配规则计算双参数反正切。
QueryBuilder.atan2(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
between()保留位于包含上下界的字面量数字范围内的向量样本。
QueryBuilder.between(minimum: Number, maximum: Number) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
minimumint | float | QueryBuilder必填包含边界的样本值下界，应不大于 maximum；between() 要求数字字面量。
maximumint | float | QueryBuilder必填包含边界的样本值上界，应不小于 minimum；between() 要求数字字面量。

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

查看声明 ↗此方法的链接
bool()让比较返回 0 或 1，而不是过滤假值样本；应作用于比较表达式。
QueryBuilder.bool() -> QueryBuilder

无参数。

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

示例

from metricraft import QueryBuilder as Q

Q.from_metric("up").eq(1).bool().build(mode="promql")
查看声明 ↗此方法的链接
default()使用右侧匹配值填补左侧 MetricsQL 表达式中的空缺。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.default(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
div()除以右操作数，并使用原生标量/向量类型与匹配校验。
QueryBuilder.div(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
eq()与右操作数比较：等于。向量比较默认过滤样本；追加 bool() 可返回 0/1。
QueryBuilder.eq(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
eq_any()与 MetricsQL 标量元组比较，保留等于任一成员的值。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.eq_any(*values: QueryInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
*valuesint | float | str | QueryBuilder, ...可变参数非空元组，成员必须全为标量或全为字符串。比较元组必须具有合适的数字类型。

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

查看声明 ↗此方法的链接
fill()为适用的 Prometheus 二元操作两侧设置缺失匹配的填充值。仅限 PromQL
仅限 PromQL
QueryBuilder.fill(value: Number) -> QueryBuilder

需要 features=('promql-binop-fill-modifiers',) 及对应服务器支持。

参数
参数 / 类型含义与可接受的值
valueint | float | QueryBuilder必填数字标量或标量表达式；拒绝 Python bool。计算值由后端求值。

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

查看声明 ↗此方法的链接
fill_left()为适用的 Prometheus 二元操作左侧设置缺失匹配的填充值。仅限 PromQL
仅限 PromQL
QueryBuilder.fill_left(value: Number) -> QueryBuilder

需要 features=('promql-binop-fill-modifiers',) 及对应服务器支持。

参数
参数 / 类型含义与可接受的值
valueint | float | QueryBuilder必填数字标量或标量表达式；拒绝 Python bool。计算值由后端求值。

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

查看声明 ↗此方法的链接
fill_right()为适用的 Prometheus 二元操作右侧设置缺失匹配的填充值。仅限 PromQL
仅限 PromQL
QueryBuilder.fill_right(value: Number) -> QueryBuilder

需要 features=('promql-binop-fill-modifiers',) 及对应服务器支持。

参数
参数 / 类型含义与可接受的值
valueint | float | QueryBuilder必填数字标量或标量表达式；拒绝 Python bool。计算值由后端求值。

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

查看声明 ↗此方法的链接
ge()与右操作数比较：大于等于。向量比较默认过滤样本；追加 bool() 可返回 0/1。
QueryBuilder.ge(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
group_left()启用多对一向量匹配，可选复制一侧（右侧）的标签。
QueryBuilder.group_left(*labels: str) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
*labelsstr, ...可变参数分别传入标签名。分组与匹配列表不能重复；允许空分组列表，具体函数的参数个数由 Rust 检查。

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

查看声明 ↗此方法的链接
group_left_all()复制 MetricsQL 多对一匹配右侧所有适用标签，可选添加前缀。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.group_left_all(*, prefix: str='') -> QueryBuilder
参数
参数 / 类型含义与可接受的值
prefixstr默认值： ''复制标签的字面量前缀，空字符串表示不添加前缀。

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

查看声明 ↗此方法的链接
group_right()启用一对多向量匹配，可选复制一侧（左侧）的标签。
QueryBuilder.group_right(*labels: str) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
*labelsstr, ...可变参数分别传入标签名。分组与匹配列表不能重复；允许空分组列表，具体函数的参数个数由 Rust 检查。

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

查看声明 ↗此方法的链接
group_right_all()复制 MetricsQL 一对多匹配左侧所有适用标签，可选添加前缀。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.group_right_all(*, prefix: str='') -> QueryBuilder
参数
参数 / 类型含义与可接受的值
prefixstr默认值： ''复制标签的字面量前缀，空字符串表示不添加前缀。

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

查看声明 ↗此方法的链接
gt()与右操作数比较：大于。向量比较默认过滤样本；追加 bool() 可返回 0/1。
QueryBuilder.gt(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
if_()仅在右侧存在匹配样本的位置保留左侧 MetricsQL 样本。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.if_(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
ifnot()仅在右侧不存在匹配样本的位置保留左侧 MetricsQL 样本。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.ifnot(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
ignoring()匹配向量时忽略指定标签，不能与 on() 同时使用。
QueryBuilder.ignoring(*labels: str) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
*labelsstr, ...可变参数分别传入标签名。分组与匹配列表不能重复；允许空分组列表，具体函数的参数个数由 Rust 检查。

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

查看声明 ↗此方法的链接
le()与右操作数比较：小于等于。向量比较默认过滤样本；追加 bool() 可返回 0/1。
QueryBuilder.le(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
lt()与右操作数比较：小于。向量比较默认过滤样本；追加 bool() 可返回 0/1。
QueryBuilder.lt(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
mod()对其取余：右操作数，并使用原生标量/向量类型与匹配校验。
QueryBuilder.mod(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
mul()乘以右操作数，并使用原生标量/向量类型与匹配校验。
QueryBuilder.mul(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
ne()与右操作数比较：不等于。向量比较默认过滤样本；追加 bool() 可返回 0/1。
QueryBuilder.ne(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
ne_all()与 MetricsQL 标量元组比较，保留不等于任何成员的值。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.ne_all(*values: QueryInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
*valuesint | float | str | QueryBuilder, ...可变参数非空元组，成员必须全为标量或全为字符串。比较元组必须具有合适的数字类型。

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

查看声明 ↗此方法的链接
negative()对数值表达式取负。
QueryBuilder.negative() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
on()只使用指定标签匹配向量操作数；应作用于支持匹配的二元表达式。
QueryBuilder.on(*labels: str) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
*labelsstr, ...可变参数分别传入标签名。分组与匹配列表不能重复；允许空分组列表，具体函数的参数个数由 Rust 检查。

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

示例

from metricraft import QueryBuilder as Q

(Q.from_metric("errors_total") / Q.from_metric("requests_total")).on("job").build(mode="promql")
查看声明 ↗此方法的链接
or_()合并两个向量，标签集相同时优先保留左侧序列。
QueryBuilder.or_(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
parenthesize()为表达式添加显式括号，不改变其值。
QueryBuilder.parenthesize() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
positive()对数值表达式应用一元正号。
QueryBuilder.positive() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
pow()取其为指数进行乘方：右操作数，并使用原生标量/向量类型与匹配校验。
QueryBuilder.pow(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
sub()减去右操作数，并使用原生标量/向量类型与匹配校验。
QueryBuilder.sub(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
trim_lower()移除 Prometheus 原生直方图中低于阈值的观测，必要时插值边界桶。仅限 PromQL
仅限 PromQL
QueryBuilder.trim_lower(threshold: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
thresholdint | float | QueryBuilder必填直方图观测值的数字截断阈值，向量阈值遵循匹配规则。

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

查看声明 ↗此方法的链接
trim_upper()移除 Prometheus 原生直方图中超过阈值的观测，必要时插值边界桶。仅限 PromQL
仅限 PromQL
QueryBuilder.trim_upper(threshold: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
thresholdint | float | QueryBuilder必填直方图观测值的数字截断阈值，向量阈值遵循匹配规则。

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

查看声明 ↗此方法的链接
union()使用 union 函数组合 MetricsQL 向量。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.union(*others: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
*othersQueryBuilder, ...可变参数额外输入表达式。多个聚合输入和 union 类转换仅限 MetricsQL；普通 PromQL 聚合只接收当前表达式。

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

查看声明 ↗此方法的链接
unless()保留没有匹配右侧序列的左侧序列。
QueryBuilder.unless(other: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
otherint | float | QueryBuilder必填右操作数。集合运算与向量匹配需要向量表达式，算术和比较也接受数字。拒绝 Python bool。

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

查看声明 ↗此方法的链接
在 GitHub 查看本页 ↗
浏览文档

查找你需要的内容

搜索指南、示例和 Python API。

    本地搜索 · 无跟踪esc 关闭