HTTP 客户端 · MetriCraft

执行即时查询、范围查询、元数据请求和 VictoriaMetrics 写入。

客户端可独立于原生构建器接收查询字符串，不解析或清理已保存的查询文本。应用授权与持久化仍由应用负责。

from metricraft import DatabaseClient, PrometheusConfig

with DatabaseClient(PrometheusConfig("http://localhost:9090")) as client:
    result = client.query("up")
    print(result.result)

异步方法可以等待，支持 async with DatabaseClient(...)。使用 MetricsQueryResult 检查返回数据。查询和元数据支持两种后端，写入仅限 VictoriaMetrics。网络示例需要运行中的后端。

方法与参数

在本页查找

DatabaseClient

DatabaseClient()从显式配置或已注册实例创建客户端，使用上下文管理器释放传输资源。

DatabaseClient(config: Optional[Config]=None, *, instance: Optional[str]=None) -> None

请求方法可能抛出 MCHTTPError、TimeoutError、ConnectionError 或参数校验错误。使用 with/async with 清理资源。

参数
参数 / 类型	含义与可接受的值
`config`Config \| None默认值： None	PrometheusConfig、VMSingleConfig 或 VMClusterConfig。config 与 instance 不能同时传入；均省略时解析已注册的默认配置。
`instance`str \| None默认值： None	可选配置注册表中的名称。未知或未设置的名称会在请求前报错。

返回值 None

参数 / 类型	含义与可接受的值
`data`MetricsInsertData \| Iterable[MetricsInsertData]必填	已验证的写入载荷，可以为一项或多项。时间戳与值必须非空且对齐，仅支持 VictoriaMetrics 写入。
`account_id`int \| None默认值： None	非负整数 VictoriaMetrics 集群租户 ID。非集群配置不接受请求级覆盖。
`custom_params`dict[str, Any] \| None默认值： None	在标准参数之后合并的额外请求参数，同名键可覆盖标准参数。值与授权由调用方负责，不做注入校验。

参数 / 类型	含义与可接受的值
`label_name`str必填	要查询已知值的标签名，例如 'job'。
`start`int \| float \| str \| datetime \| None默认值： None	包含边界的范围起点或元数据时间下界。query_range 默认取 end 之前一小时；元数据调用在 None 时省略该边界。
`end`int \| float \| str \| datetime \| None默认值： None	包含边界的范围终点或元数据时间上界。query_range 默认取当前时间；元数据调用在 None 时省略该边界。
`match`str \| QueryBuilder \| Sequence[str \| QueryBuilder] \| None默认值： None	一个或多个序列选择器，支持列表和元组。构建器按后端方言渲染；series() 必须提供，labels/label_values 可以省略。
`limit`int \| None默认值： None	非负的序列或元数据结果限制，0 表示不限。查询序列限制仅适用于 Prometheus，VictoriaMetrics 可能忽略它。
`account_id`int \| None默认值： None	非负整数 VictoriaMetrics 集群租户 ID。非集群配置不接受请求级覆盖。
`custom_params`dict[str, Any] \| None默认值： None	在标准参数之后合并的额外请求参数，同名键可覆盖标准参数。值与授权由调用方负责，不做注入校验。

参数 / 类型	含义与可接受的值
`query`str \| QueryBuilder必填	保存的查询文本或构建器。构建器使用所配置后端的方言；字符串原样发送，不解析或提供注入防护。
`time`int \| float \| str \| datetime \| None默认值： None	求值时间戳。数字为 Unix 秒（绝对值超过 1e10 时按毫秒处理）；接受带时区 datetime 和后端时间字符串。None 使用服务器当前时间。
`timeout`str \| None默认值： None	后端查询执行超时，如 '30s'；None 时省略。传输套接字超时应单独使用 HttpClientOptions 配置。
`step`str \| None默认值： None	范围查询的正求值间隔，如 '30s'，默认 config.default_step。即时查询中，这是 VictoriaMetrics 专有的回看选项。
`limit`int \| None默认值： None	非负的序列或元数据结果限制，0 表示不限。查询序列限制仅适用于 Prometheus，VictoriaMetrics 可能忽略它。
`extra_label`str \| dict[str, str] \| None默认值： None	VictoriaMetrics 专有的额外等值过滤，如 {'tenant': 'demo'} 或 'tenant=demo'，不能替代服务器授权。
`extra_filters`str \| list[str] \| None默认值： None	VictoriaMetrics 专有的额外选择器过滤，如 '{env="prod"}'。该客户端选项中的查询文本不会被构建器清理。
`round_digits`int \| None默认值： None	VictoriaMetrics 响应舍入精度，直接传给后端，SDK 不强制数值边界。
`nocache`bool \| None默认值： None	VictoriaMetrics 专有开关，为 True 时绕过查询缓存。
`trace`bool \| None默认值： None	VictoriaMetrics 专有开关，用于请求执行跟踪详情。
`account_id`int \| None默认值： None	非负整数 VictoriaMetrics 集群租户 ID。非集群配置不接受请求级覆盖。
`custom_params`dict[str, Any] \| None默认值： None	在标准参数之后合并的额外请求参数，同名键可覆盖标准参数。值与授权由调用方负责，不做注入校验。