时间窗口计算 · MetriCraft

从即时选择器开始时应给出窗口，也可以对已有范围表达式应用窗口函数。裸选择器不指定窗口时，会选择 MetricsQL 的隐式 rollup 行为，无法构建为 PromQL。

from metricraft import QueryBuilder as Q

counter = Q.from_metric("requests_total")
print(counter.rate("5m").build(mode="promql"))
gauge = Q.from_metric("temperature_celsius")
print(gauge.avg_over_time("10m").build(mode="promql"))

计数器使用 rate、increase，仪表值使用 delta、deriv。函数同名不代表 Prometheus 和 VictoriaMetrics 的窗口边界行为相同。window 与兼容别名 duration 互斥。

方法与参数

在本页查找

QueryBuilder

absent_over_time()范围输入没有样本时返回 1，否则不返回序列。

QueryBuilder.absent_over_time(window: Optional[Window]=None, *, duration: Optional[Window]=None) -> QueryBuilder

参数
参数 / 类型	含义与可接受的值
`window`str \| QueryBuilder \| None默认值： None	正回看时长，如 '5m' 或 '1h30m'。None 保留已有范围或使用 MetricsQL 隐式 rollup；无窗口的裸选择器不能构建为 PromQL。时长表达式需要对应方言或功能支持。
`duration`str \| QueryBuilder \| None默认值： None	回看时长，如 '5m'。也接受 window 时只能选一个名称。None 保留当前范围或请求 MetricsQL 隐式 rollup。

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

参数 / 类型	含义与可接受的值
`window`str \| QueryBuilder \| None默认值： None	正回看时长，如 '5m' 或 '1h30m'。None 保留已有范围或使用 MetricsQL 隐式 rollup；无窗口的裸选择器不能构建为 PromQL。时长表达式需要对应方言或功能支持。
`smoothing_factor`int \| float \| QueryBuilder默认值： 0.3	严格位于 0 和 1 之间的水平平滑因子。越大越重视近期样本，字面量因子由 Rust 校验。
`trend_factor`int \| float \| QueryBuilder默认值： 0.3	严格位于 0 和 1 之间的趋势平滑因子，字面量因子由 Rust 校验。

参数 / 类型	含义与可接受的值
`seconds`int \| float \| QueryBuilder \| None默认值： None	预测时长，单位为秒。正值向未来预测；seconds 与 prediction_seconds 必须提供一个且不能同时提供。
`window`str \| QueryBuilder \| None默认值： None	正回看时长，如 '5m' 或 '1h30m'。None 保留已有范围或使用 MetricsQL 隐式 rollup；无窗口的裸选择器不能构建为 PromQL。时长表达式需要对应方言或功能支持。
`prediction_seconds`int \| float \| QueryBuilder \| None默认值： None	seconds 的别名，不能同时传入两者。
`duration`str \| QueryBuilder \| None默认值： None	回看时长，如 '5m'。也接受 window 时只能选一个名称。None 保留当前范围或请求 MetricsQL 隐式 rollup。

参数 / 类型	含义与可接受的值
`q`int \| float \| QueryBuilder \| None默认值： None	分位数，通常在 [0, 1] 内。q 与 quantile 只能提供一个；只有别名提供值时才允许 None。
`window`str \| QueryBuilder \| None默认值： None	正回看时长，如 '5m' 或 '1h30m'。None 保留已有范围或使用 MetricsQL 隐式 rollup；无窗口的裸选择器不能构建为 PromQL。时长表达式需要对应方言或功能支持。
`quantile`int \| float \| QueryBuilder \| None默认值： None	q 的别名。q 与 quantile 必须且只能提供一个，通常使用 [0, 1]。
`duration`str \| QueryBuilder \| None默认值： None	回看时长，如 '5m'。也接受 window 时只能选一个名称。None 保留当前范围或请求 MetricsQL 隐式 rollup。

参数 / 类型	含义与可接受的值
`window`str \| QueryBuilder \| None默认值： None	正回看时长，如 '5m' 或 '1h30m'。None 保留已有范围或使用 MetricsQL 隐式 rollup；无窗口的裸选择器不能构建为 PromQL。时长表达式需要对应方言或功能支持。
`result`str \| None默认值： None	选择 'min'、'max' 或 'avg'；None 输出全部三种结果序列。
`duration`str \| QueryBuilder \| None默认值： None	回看时长，如 '5m'。也接受 window 时只能选一个名称。None 保留当前范围或请求 MetricsQL 隐式 rollup。