参考手册
构建与诊断
渲染查询、限制输出预算，并检查原生表达式图。
诊断是只读操作，不向服务器发送查询。结构分析描述表达式图，不是执行计划，也不承诺后端成本。
from metricraft import QueryBuilder as Q
query = Q.from_metric("up").sum().by("job")
assert query.validate("promql") == ""
print(query.analyze())
print(query.debug_positions(mode="promql"))图诊断对共享节点只计数一次。渲染源码位置描述每次出现，使用 UTF-8 字节偏移。两类诊断都受输出与工作预算约束。
debug() 和 to_debug_json() 返回 schema-1 图 JSON，子节点和持久化匹配器链接使用 ID 引用。analyze() 返回独立摘要，包含唯一节点、名称、结构复杂度和启发式发现。图与分析默认限制为 1 MiB 输出和 10,000 个工作项（根节点、子边和唯一匹配器链接）。单次调用可用正的 max_output_bytes、max_items 覆盖。
debug_positions() 使用与 build() 相同的原生渲染器和方言检查。范围信息描述表达式的各次出现，匹配器细节属于图诊断。visualize_positions(source_code) 先核对传入文本与渲染查询完全一致，再返回源码与范围 JSON，应用可自行呈现。位置诊断展开每次出现，同时限制工作量和序列化输出。快照是独立返回值，不向持久节点增加缓存字符串或诊断字段。
方法与参数
QueryBuilder
analyze()检查共享原生图，以 Python 字典返回计数与结构启发信息。
QueryBuilder.analyze(*, max_output_bytes: Optional[int]=None, max_items: Optional[int]=None) -> Dict[str, Any]
| 参数 / 类型 | 含义与可接受的值 |
|---|---|
max_output_bytesint | None默认值： None | 正整数字节预算。None 使用原生默认值 1 MiB，拒绝 bool 和零。按 UTF-8 字节而不是字符数计量。 |
max_itemsint | None默认值： None | 正整数诊断工作预算，None 使用原生默认值。图检查计数节点、边和匹配器链接；位置输出计数渲染出现次数。 |
返回值 dict：图计数与启发建议，不是服务器执行计划。
示例
from metricraft import QueryBuilder as Q
Q.from_metric("up").sum().analyze()debug()序列化有界诊断图，共享节点与匹配器链接只输出一次。
QueryBuilder.debug(*, max_output_bytes: Optional[int]=None, max_items: Optional[int]=None) -> str
| 参数 / 类型 | 含义与可接受的值 |
|---|---|
max_output_bytesint | None默认值： None | 正整数字节预算。None 使用原生默认值 1 MiB，拒绝 bool 和零。按 UTF-8 字节而不是字符数计量。 |
max_itemsint | None默认值： None | 正整数诊断工作预算，None 使用原生默认值。图检查计数节点、边和匹配器链接；位置输出计数渲染出现次数。 |
返回值 str：描述唯一原生节点及其关系的 JSON。
debug_positions()以 JSON 字符串返回查询文本和表达式各次出现的 UTF-8 字节范围。
QueryBuilder.debug_positions(*, mode: BuildMode=QueryMode.METRICSQL, max_output_bytes: Optional[int]=None, max_items: Optional[int]=None, experimental_functions: bool=False, features: Iterable[str]=()) -> str
| 参数 / 类型 | 含义与可接受的值 |
|---|---|
modeQueryMode | str默认值： QueryMode.METRICSQL | 'promql' 或默认的 'metricsql'。检查完整表达式，包括方言专属参数形式。 |
max_output_bytesint | None默认值： None | 正整数字节预算。None 使用原生默认值 1 MiB，拒绝 bool 和零。按 UTF-8 字节而不是字符数计量。 |
max_itemsint | None默认值： None | 正整数诊断工作预算，None 使用原生默认值。图检查计数节点、边和匹配器链接；位置输出计数渲染出现次数。 |
experimental_functionsbool默认值： False | 启用 Prometheus 实验函数。后端也必须启用对应功能，此开关不配置服务器。 |
featuresIterable[str]默认值： () | 显式功能名：'promql-experimental-functions'、'promql-duration-expr'、'promql-extended-range-selectors'、'promql-binop-fill-modifiers'。各项都需要对应服务器支持。请传集合，不要传单个字符串。 |
返回值 str：包含查询文本与 UTF-8 字节范围的 JSON，不是 Python 字符偏移。
to_debug_json()序列化有界诊断图，共享节点与匹配器链接只输出一次。
QueryBuilder.to_debug_json(*, max_output_bytes: Optional[int]=None, max_items: Optional[int]=None) -> str
| 参数 / 类型 | 含义与可接受的值 |
|---|---|
max_output_bytesint | None默认值： None | 正整数字节预算。None 使用原生默认值 1 MiB，拒绝 bool 和零。按 UTF-8 字节而不是字符数计量。 |
max_itemsint | None默认值： None | 正整数诊断工作预算，None 使用原生默认值。图检查计数节点、边和匹配器链接；位置输出计数渲染出现次数。 |
返回值 str：描述唯一原生节点及其关系的 JSON。
validate()构建有效时返回空字符串，否则返回原生验证错误文本；不会绕过验证。
QueryBuilder.validate(standard: Optional[str]=None, strict: bool=True, **build_options: Any) -> str
| 参数 / 类型 | 含义与可接受的值 |
|---|---|
standardstr | None默认值： None | 'promql' 或 'metricsql'，不区分大小写。None 选择 MetricsQL。 |
strictbool默认值： True | 必须为 True，有意不支持 strict=False。 |
**build_options关键字参数可变参数 | build() 接受的关键字选项，不含 mode（这里使用 standard）。预算和功能校验仍然生效。 |
返回值 str：成功时为空，否则为原生验证消息；无效 Python 参数仍可能抛出异常。