参考手册
时间与范围
设置回看窗口、子查询、偏移、固定求值时间和时间函数。
范围从选择器中选取原始样本，子查询则重复计算一个已组合的表达式。两者都不是客户端请求；DatabaseClient.query_range() 才是执行 I/O 的操作。
from metricraft import QueryBuilder as Q
query = (Q.from_metric("requests_total").rate("5m")
.subquery("1h", "1m").max_over_time())
print(query.build(mode="promql"))使用 5m、1h30m 等正时长字符串。Prometheus 的时长表达式与扩展范围选择器需要显式启用相应功能，服务器也必须启用同一功能。
方法与参数
QueryBuilder
anchored()为适用的 Prometheus 范围选择器扩展锚定边界样本，仅受支持的窗口函数接受它。仅限 PromQL
at()在固定 Unix 时间戳或外围查询的 start/end 时间计算选择器或子查询。
QueryBuilder.at(timestamp: Union[Number, str, datetime, QueryBuilder]) -> QueryBuilder
| 参数 / 类型 | 含义与可接受的值 |
|---|---|
timestampint | float | str | datetime | QueryBuilder必填 | 有限 Unix 秒、带时区 datetime/ISO 字符串、'start'/'end'（也接受 'start()'/'end()'），或支持的有类型标量表达式。拒绝无时区 datetime 和 bool。 |
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。
示例
from metricraft import QueryBuilder as Q
Q.from_metric("up").at("2026-01-01T00:00:00Z").build(mode="promql")end()创建外围查询结束时间戳的标量。
from_end()创建外围查询结束时间戳的标量。
from_now()创建表示后端当前时钟时间的 MetricsQL 标量。仅限 MetricsQL
from_start()创建外围查询起始时间戳的标量。
from_time()创建表示求值时刻的 Unix 秒标量。
now()创建表示后端当前时钟时间的 MetricsQL 标量。仅限 MetricsQL
offset()移动选择器或子查询的时间。正偏移向过去看，负偏移向未来看。
query_range()创建表示外围查询时长的 Prometheus range() 标量，不是客户端范围请求。仅限 PromQL
range()选择原始样本的回看范围。对于已计算的 PromQL 向量，应使用 subquery()。
QueryBuilder.range(window: Optional[Window]=None, *, duration: Optional[Window]=None) -> QueryBuilder
不传参数时默认为 '5m'。对于已经计算的 PromQL 表达式，请使用 subquery()。
| 参数 / 类型 | 含义与可接受的值 |
|---|---|
windowstr | QueryBuilder | None默认值： None | 正回看时长，如 '5m' 或 '1h30m'。None 保留已有范围或使用 MetricsQL 隐式 rollup；无窗口的裸选择器不能构建为 PromQL。时长表达式需要对应方言或功能支持。 |
durationstr | QueryBuilder | None默认值： None | 回看时长，如 '5m'。也接受 window 时只能选一个名称。None 保留当前范围或请求 MetricsQL 隐式 rollup。 |
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。
smoothed()为适用的 Prometheus 范围选择器扩展平滑边界处理，仅受支持的窗口函数接受它。仅限 PromQL
start()创建外围查询起始时间戳的标量。
start_timestamp()在可用时返回原生直方图的开始时间戳。仅限 PromQL
step()创建外围查询求值步长的秒数标量。
subquery()在回看区间内重复计算组合表达式，生成范围向量。
QueryBuilder.subquery(window: Optional[Window]=None, step: Optional[Window]=None, *, range_duration: Optional[Window]=None, resolution: Optional[Window]=None) -> QueryBuilder
PromQL 要求显式的正窗口，MetricsQL 可以省略。时长表达式形式需要启用对应功能。
| 参数 / 类型 | 含义与可接受的值 |
|---|---|
windowstr | QueryBuilder | None默认值： None | 正回看时长，如 '5m' 或 '1h30m'。None 保留已有范围或使用 MetricsQL 隐式 rollup；无窗口的裸选择器不能构建为 PromQL。时长表达式需要对应方言或功能支持。 |
stepstr | QueryBuilder | None默认值： None | 正的子查询求值步长，如 '30s'。None 使用后端默认子查询分辨率。 |
range_durationstr | QueryBuilder | None默认值： None | subquery() 中 window 的别名，不要同时传入两个名称。 |
resolutionstr | QueryBuilder | None默认值： None | subquery() 中 step 的别名，不要同时传入两个名称。 |
返回值 QueryBuilder：共享未变化原生子树的新不可变表达式。接收表达式不变，不查询数据。
示例
from metricraft import QueryBuilder as Q
Q.from_metric("requests_total").rate("5m").subquery("1h", "1m").max_over_time().build(mode="promql")