MetriCraft/文档
EnglishGitHub
参考手册

MetricsQL 转换

处理查询区间内的缺失值、异常值、累计统计和序列转换。

与滑动窗口计算不同，range_* 汇总整个 MetricsQL 返回区间，running_* 从区间起点开始累计。它们的含义取决于范围请求的 start、end 和 step。

from metricraft import QueryBuilder as Q

query = Q.from_metric("queue_depth").keep_last_value().range_avg()
print(query.build(mode="metricsql"))

这些方法只构建表达式，不加载样本，也不在 Python 中执行转换。histogram_quantiles() 还支持显式的 Prometheus 实验形式。

方法与参数

QueryBuilder

bitmap_and()按 MetricsQL 整数转换规则，对样本值和数字掩码执行按位 AND。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.bitmap_and(value: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
valueint | float | QueryBuilder必填数字标量或标量表达式；拒绝 Python bool。计算值由后端求值。

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

查看声明 ↗此方法的链接
bitmap_or()按 MetricsQL 整数转换规则，对样本值和数字掩码执行按位 OR。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.bitmap_or(value: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
valueint | float | QueryBuilder必填数字标量或标量表达式；拒绝 Python bool。计算值由后端求值。

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

查看声明 ↗此方法的链接
bitmap_xor()按 MetricsQL 整数转换规则，对样本值和数字掩码执行按位 XOR。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.bitmap_xor(value: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
valueint | float | QueryBuilder必填数字标量或标量表达式；拒绝 Python bool。计算值由后端求值。

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

查看声明 ↗此方法的链接
buckets_limit()减少 MetricsQL 直方图的桶数。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.buckets_limit(value: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
valueint | float | QueryBuilder必填直方图桶数上限，应使用正整数。

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

查看声明 ↗此方法的链接
drop_empty_series()移除整个请求区间都没有值的 MetricsQL 序列。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.drop_empty_series() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
histogram_quantiles()估算多个直方图分位数，添加标签标识所请求的分位数；构建器按方言选择参数顺序。
Prometheus 实验功能
QueryBuilder.histogram_quantiles(label: StringInput, *quantiles: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
labelstr必填不含控制字符的非空标签名。方言要求时，构建器会为名称加引号。
*quantilesint | float | QueryBuilder, ...可变参数一个或多个分位数，通常各自在 [0, 1] 内。PromQL histogram_quantiles 最多接受 10 个，MetricsQL 支持自己的可变参数形式。

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

查看声明 ↗此方法的链接
histogram_share()估算 MetricsQL 直方图中小于等于边界的观测值比例。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.histogram_share(bound: ScalarInput, *, bounds_label: Optional[StringInput]=None) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
boundint | float | QueryBuilder必填用于累计占比的直方图观测值边界。
bounds_labelstr | None默认值： None可选的上下估算边界输出标签。提供该参数会选择仅限 MetricsQL 的参数形式。

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

查看声明 ↗此方法的链接
interpolate()通过线性插值填补 MetricsQL 已知样本之间的空缺。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.interpolate() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
keep_last_value()在 MetricsQL 范围查询中使用前一个已知样本填补空缺。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.keep_last_value() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
keep_next_value()在 MetricsQL 范围查询中使用后一个已知样本填补空缺。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.keep_next_value() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
limit_offset()跳过一定数量的输出序列，再返回不超过限制数量的序列。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.limit_offset(limit: ScalarInput, offset: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
limitint | float | QueryBuilder必填输出序列数量上限，应使用非负整数。计算得到的值由后端处理。
offsetint | float | QueryBuilder必填跳过的输出序列数量，应使用非负整数。

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

查看声明 ↗此方法的链接
prometheus_buckets()将 VictoriaMetrics 直方图桶标签转换为 Prometheus 的 le 桶标签。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.prometheus_buckets() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
rand()创建 MetricsQL 均匀分布随机值，可选指定种子。仅限 MetricsQL
类方法仅限 MetricsQL
QueryBuilder.rand(seed: Optional[ScalarInput]=None) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
seedint | float | QueryBuilder | None默认值： None可选标量随机种子。None 使用后端默认种子策略，构建器不在本地生成随机样本。

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

查看声明 ↗此方法的链接
rand_exponential()创建 MetricsQL 指数分布随机值，可选指定种子。仅限 MetricsQL
类方法仅限 MetricsQL
QueryBuilder.rand_exponential(seed: Optional[ScalarInput]=None) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
seedint | float | QueryBuilder | None默认值： None可选标量随机种子。None 使用后端默认种子策略，构建器不在本地生成随机样本。

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

查看声明 ↗此方法的链接
rand_normal()创建 MetricsQL 正态分布随机值，可选指定种子。仅限 MetricsQL
类方法仅限 MetricsQL
QueryBuilder.rand_normal(seed: Optional[ScalarInput]=None) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
seedint | float | QueryBuilder | None默认值： None可选标量随机种子。None 使用后端默认种子策略，构建器不在本地生成随机样本。

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

查看声明 ↗此方法的链接
range_avg()计算整个 MetricsQL 查询区间的算术平均值，而不是滑动回看窗口。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_avg() -> QueryBuilder

无参数。

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

示例

from metricraft import QueryBuilder as Q

Q.from_metric("queue_depth").range_avg().build(mode="metricsql")
查看声明 ↗此方法的链接
range_first()计算整个 MetricsQL 查询区间的第一个值，而不是滑动回看窗口。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_first() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
range_last()计算整个 MetricsQL 查询区间的最后一个值，而不是滑动回看窗口。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_last() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
range_linear_regression()将 MetricsQL 范围查询序列替换为其拟合回归线。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_linear_regression() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
range_mad()计算整个 MetricsQL 查询区间的中位绝对偏差，而不是滑动回看窗口。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_mad() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
range_max()计算整个 MetricsQL 查询区间的最大值，而不是滑动回看窗口。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_max() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
range_median()计算整个 MetricsQL 查询区间的中位数，而不是滑动回看窗口。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_median() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
range_min()计算整个 MetricsQL 查询区间的最小值，而不是滑动回看窗口。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_min() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
range_normalize()使用整个范围内的最小值与最大值规范化 MetricsQL 范围查询样本。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_normalize(*others: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
*othersQueryBuilder, ...可变参数额外输入表达式。多个聚合输入和 union 类转换仅限 MetricsQL；普通 PromQL 聚合只接收当前表达式。

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

查看声明 ↗此方法的链接
range_quantile()将 MetricsQL 范围查询序列替换为整个请求区间的分位数。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_quantile(value: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
valueint | float | QueryBuilder必填请求的分位数，通常在 [0, 1] 内。范围外的值遵循后端分位数语义，构建器不会一律拒绝。

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

查看声明 ↗此方法的链接
range_stddev()计算整个 MetricsQL 查询区间的总体标准差，而不是滑动回看窗口。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_stddev() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
range_stdvar()计算整个 MetricsQL 查询区间的总体方差，而不是滑动回看窗口。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_stdvar() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
range_sum()计算整个 MetricsQL 查询区间的总和，而不是滑动回看窗口。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_sum() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
range_trim_outliers()删除与区间中位数的距离超过缩放中位绝对偏差的样本。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_trim_outliers(value: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
valueint | float | QueryBuilder必填中位绝对偏差的乘数，应使用非负值，由后端求值。

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

查看声明 ↗此方法的链接
range_trim_spikes()移除查询区间内指定比例的上下极端样本。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_trim_spikes(value: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
valueint | float | QueryBuilder必填要裁剪的极端样本比例，通常在 [0, 1] 内，由后端求值。

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

查看声明 ↗此方法的链接
range_trim_zscore()移除 z-score 绝对值超过给定阈值的样本。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_trim_zscore(value: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
valueint | float | QueryBuilder必填非负的 z-score 绝对值阈值，例如 3。

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

查看声明 ↗此方法的链接
range_zscore()计算整个 MetricsQL 查询区间的z-score，而不是滑动回看窗口。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.range_zscore() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
remove_resets()调整计数器序列，消除向下重置产生的不连续。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.remove_resets() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
ru()根据接收表达式的剩余容量和给定最大容量，计算 MetricsQL 资源利用率百分比。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.ru(value: ScalarInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
valueint | float | QueryBuilder必填作为利用率分母的最大资源容量，必须为正。

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

查看声明 ↗此方法的链接
running_avg()从 MetricsQL 范围查询起点到各求值时刻，计算累计算术平均值。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.running_avg() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
running_max()从 MetricsQL 范围查询起点到各求值时刻，计算累计最大值。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.running_max() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
running_min()从 MetricsQL 范围查询起点到各求值时刻，计算累计最小值。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.running_min() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
running_sum()从 MetricsQL 范围查询起点到各求值时刻，计算累计总和。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.running_sum() -> QueryBuilder

无参数。

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

查看声明 ↗此方法的链接
timezone_offset()创建命名时区在求值时刻相对于 UTC 的偏移秒数标量。仅限 MetricsQL
类方法仅限 MetricsQL
QueryBuilder.timezone_offset(timezone: StringInput) -> QueryBuilder
参数
参数 / 类型含义与可接受的值
timezonestr必填IANA 时区名，如 'Europe/Paris' 或 'UTC'，是否存在由后端时区数据库检查。

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

查看声明 ↗此方法的链接
ttf()根据下降的仪表值估算到达零值的时间，即预计失效时间。仅限 MetricsQL
仅限 MetricsQL
QueryBuilder.ttf() -> QueryBuilder

无参数。

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

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

查找你需要的内容

搜索指南、示例和 Python API。

    本地搜索 · 无跟踪esc 关闭