Reference
Client & requests
Execute saved queries, read metadata and manage sync/async transports.
The client accepts query strings independently of the native builder. It does not parse or sanitize stored query strings. Application authorization and persistence remain with your application.
from metricraft import DatabaseClient, PrometheusConfig
with DatabaseClient(PrometheusConfig("http://localhost:9090")) as client:
result = client.query("up")
print(result.result)Async methods are awaitable and support async with DatabaseClient(...). Use MetricsQueryResult to inspect returned data. Queries and metadata work with both backends; insertion is VictoriaMetrics-specific. Network examples require a running backend.
Methods and parameters
DatabaseClient
DatabaseClient()Create a client from an explicit configuration or registered instance. Use a context manager to release transports.
DatabaseClient(config: Optional[Config]=None, *, instance: Optional[str]=None) -> None
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
| Parameter / type | Meaning and accepted values |
|---|---|
configConfig | NoneDefault: None | PrometheusConfig, VMSingleConfig or VMClusterConfig. Supply config or instance, not both; with neither, resolve the registered default. |
instancestr | NoneDefault: None | Name in the optional configuration registry. Unknown/unset names fail before requests. |
Returns None
aclose()Await asynchronous cleanup and release the synchronous transport.
async
DatabaseClient.aclose() -> None
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
No parameters.
Returns None
async_clientAccess the active asynchronous HTTP transport.
property
DatabaseClient.async_client
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
No parameters.
Returns Optional[AsyncHTTPTransport]
clientAccess the active synchronous HTTP transport.
property
DatabaseClient.client
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
No parameters.
Returns SyncHTTPTransport
close()Release owned transports once. Use aclose() when asynchronous cleanup is required.
DatabaseClient.close() -> None
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
No parameters.
Returns None
closedWhether the client has been closed. Closed clients reject further requests.
property
DatabaseClient.closed
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
No parameters.
Returns bool
get_connection_info()Return a shallow copy of active backend connection settings.
DatabaseClient.get_connection_info() -> Dict[str, Any]
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
No parameters.
Returns Dict[str, Any]
health()Check the configured backend's health endpoint and return whether it is reachable and healthy.
DatabaseClient.health() -> bool
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
No parameters.
Returns bool
health_async()Check the configured backend's health endpoint and return whether it is reachable and healthy. Await this asynchronous variant.
async
DatabaseClient.health_async() -> bool
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
No parameters.
Returns bool
insert()Send samples to VictoriaMetrics' ingestion endpoint. PrometheusConfig raises NotImplementedError.
DatabaseClient.insert(data: Union[MetricsInsertData, Iterable[MetricsInsertData]], *, account_id: Optional[int]=None, custom_params: Optional[Dict[str, Any]]=None) -> Dict[str, Any]
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
| Parameter / type | Meaning and accepted values |
|---|---|
dataMetricsInsertData | Iterable[MetricsInsertData]Required | Validated ingestion payload(s). Nonempty aligned timestamps/values are required. Only VictoriaMetrics ingestion is supported. |
account_idint | NoneDefault: None | Nonnegative integer VictoriaMetrics cluster tenant ID. A per-request override is rejected for non-cluster configurations. |
custom_paramsdict[str, Any] | NoneDefault: None | Additional request parameters merged after standard parameters, so duplicate keys can override them. Values and authorization remain caller-owned; no injection validation is performed. |
Returns Dict[str, Any]
insert_async()Send samples to VictoriaMetrics' ingestion endpoint. PrometheusConfig raises NotImplementedError. Await this asynchronous variant.
async
DatabaseClient.insert_async(data: Union[MetricsInsertData, Iterable[MetricsInsertData]], *, account_id: Optional[int]=None, custom_params: Optional[Dict[str, Any]]=None) -> Dict[str, Any]
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
| Parameter / type | Meaning and accepted values |
|---|---|
dataMetricsInsertData | Iterable[MetricsInsertData]Required | Validated ingestion payload(s). Nonempty aligned timestamps/values are required. Only VictoriaMetrics ingestion is supported. |
account_idint | NoneDefault: None | Nonnegative integer VictoriaMetrics cluster tenant ID. A per-request override is rejected for non-cluster configurations. |
custom_paramsdict[str, Any] | NoneDefault: None | Additional request parameters merged after standard parameters, so duplicate keys can override them. Values and authorization remain caller-owned; no injection validation is performed. |
Returns Dict[str, Any]
insert_base_url()Return the VictoriaMetrics insertion base URL; unsupported for Prometheus.
DatabaseClient.insert_base_url() -> str
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
No parameters.
Returns str
label_values()List known values of one label, optionally restricted by selectors and time bounds.
DatabaseClient.label_values(label_name: str, start: Optional[TimeValue]=None, end: Optional[TimeValue]=None, *, match: Optional[MatchInput]=None, limit: Optional[int]=None, account_id: Optional[int]=None, custom_params: Optional[Dict[str, Any]]=None) -> LabelValuesResult
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
| Parameter / type | Meaning and accepted values |
|---|---|
label_namestrRequired | Label whose known values should be returned, e.g. 'job'. |
startint | float | str | datetime | NoneDefault: None | Inclusive range start or metadata lower bound. query_range defaults to one hour before end; metadata calls omit the bound when None. |
endint | float | str | datetime | NoneDefault: None | Inclusive range end or metadata upper bound. query_range defaults to now; metadata calls omit the bound when None. |
matchstr | QueryBuilder | Sequence[str | QueryBuilder] | NoneDefault: None | One or more series selectors, including lists and tuples; builders render using the backend dialect. series() requires this argument; labels/label_values may omit it. |
limitint | NoneDefault: None | Nonnegative series/metadata result limit; 0 disables the limit. Query series limits are Prometheus-specific; VictoriaMetrics may ignore them. |
account_idint | NoneDefault: None | Nonnegative integer VictoriaMetrics cluster tenant ID. A per-request override is rejected for non-cluster configurations. |
custom_paramsdict[str, Any] | NoneDefault: None | Additional request parameters merged after standard parameters, so duplicate keys can override them. Values and authorization remain caller-owned; no injection validation is performed. |
Returns LabelValuesResult
label_values_async()List known values of one label, optionally restricted by selectors and time bounds. Await this asynchronous variant.
async
DatabaseClient.label_values_async(label_name: str, start: Optional[TimeValue]=None, end: Optional[TimeValue]=None, *, match: Optional[MatchInput]=None, limit: Optional[int]=None, account_id: Optional[int]=None, custom_params: Optional[Dict[str, Any]]=None) -> LabelValuesResult
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
| Parameter / type | Meaning and accepted values |
|---|---|
label_namestrRequired | Label whose known values should be returned, e.g. 'job'. |
startint | float | str | datetime | NoneDefault: None | Inclusive range start or metadata lower bound. query_range defaults to one hour before end; metadata calls omit the bound when None. |
endint | float | str | datetime | NoneDefault: None | Inclusive range end or metadata upper bound. query_range defaults to now; metadata calls omit the bound when None. |
matchstr | QueryBuilder | Sequence[str | QueryBuilder] | NoneDefault: None | One or more series selectors, including lists and tuples; builders render using the backend dialect. series() requires this argument; labels/label_values may omit it. |
limitint | NoneDefault: None | Nonnegative series/metadata result limit; 0 disables the limit. Query series limits are Prometheus-specific; VictoriaMetrics may ignore them. |
account_idint | NoneDefault: None | Nonnegative integer VictoriaMetrics cluster tenant ID. A per-request override is rejected for non-cluster configurations. |
custom_paramsdict[str, Any] | NoneDefault: None | Additional request parameters merged after standard parameters, so duplicate keys can override them. Values and authorization remain caller-owned; no injection validation is performed. |
Returns LabelValuesResult
labels()List label names, optionally restricted by selectors and time bounds.
DatabaseClient.labels(start: Optional[TimeValue]=None, end: Optional[TimeValue]=None, *, match: Optional[MatchInput]=None, limit: Optional[int]=None, account_id: Optional[int]=None, custom_params: Optional[Dict[str, Any]]=None) -> LabelsResult
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
| Parameter / type | Meaning and accepted values |
|---|---|
startint | float | str | datetime | NoneDefault: None | Inclusive range start or metadata lower bound. query_range defaults to one hour before end; metadata calls omit the bound when None. |
endint | float | str | datetime | NoneDefault: None | Inclusive range end or metadata upper bound. query_range defaults to now; metadata calls omit the bound when None. |
matchstr | QueryBuilder | Sequence[str | QueryBuilder] | NoneDefault: None | One or more series selectors, including lists and tuples; builders render using the backend dialect. series() requires this argument; labels/label_values may omit it. |
limitint | NoneDefault: None | Nonnegative series/metadata result limit; 0 disables the limit. Query series limits are Prometheus-specific; VictoriaMetrics may ignore them. |
account_idint | NoneDefault: None | Nonnegative integer VictoriaMetrics cluster tenant ID. A per-request override is rejected for non-cluster configurations. |
custom_paramsdict[str, Any] | NoneDefault: None | Additional request parameters merged after standard parameters, so duplicate keys can override them. Values and authorization remain caller-owned; no injection validation is performed. |
Returns LabelsResult
labels_async()List label names, optionally restricted by selectors and time bounds. Await this asynchronous variant.
async
DatabaseClient.labels_async(start: Optional[TimeValue]=None, end: Optional[TimeValue]=None, *, match: Optional[MatchInput]=None, limit: Optional[int]=None, account_id: Optional[int]=None, custom_params: Optional[Dict[str, Any]]=None) -> LabelsResult
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
| Parameter / type | Meaning and accepted values |
|---|---|
startint | float | str | datetime | NoneDefault: None | Inclusive range start or metadata lower bound. query_range defaults to one hour before end; metadata calls omit the bound when None. |
endint | float | str | datetime | NoneDefault: None | Inclusive range end or metadata upper bound. query_range defaults to now; metadata calls omit the bound when None. |
matchstr | QueryBuilder | Sequence[str | QueryBuilder] | NoneDefault: None | One or more series selectors, including lists and tuples; builders render using the backend dialect. series() requires this argument; labels/label_values may omit it. |
limitint | NoneDefault: None | Nonnegative series/metadata result limit; 0 disables the limit. Query series limits are Prometheus-specific; VictoriaMetrics may ignore them. |
account_idint | NoneDefault: None | Nonnegative integer VictoriaMetrics cluster tenant ID. A per-request override is rejected for non-cluster configurations. |
custom_paramsdict[str, Any] | NoneDefault: None | Additional request parameters merged after standard parameters, so duplicate keys can override them. Values and authorization remain caller-owned; no injection validation is performed. |
Returns LabelsResult
query()Execute an instant query against the configured Prometheus or VictoriaMetrics backend.
DatabaseClient.query(query: Union[str, QueryBuilder], time: Optional[TimeValue]=None, timeout: Optional[str]=None, *, step: Optional[str]=None, limit: Optional[int]=None, extra_label: Optional[Union[str, Dict[str, str], Iterable[str]]]=None, extra_filters: Optional[Union[str, Iterable[str]]]=None, round_digits: Optional[int]=None, nocache: Optional[bool]=None, trace: Optional[bool]=None, account_id: Optional[int]=None, custom_params: Optional[Dict[str, Any]]=None) -> MetricsQueryResult
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
| Parameter / type | Meaning and accepted values |
|---|---|
querystr | QueryBuilderRequired | Saved query text or a builder. Builders use the configured backend's dialect; strings are passed through without parsing or injection protection. |
timeint | float | str | datetime | NoneDefault: None | Evaluation timestamp. Numbers are Unix seconds (milliseconds when magnitude exceeds 1e10); aware datetimes and backend timestamp strings are accepted. None uses server now. |
timeoutstr | NoneDefault: None | Backend query execution timeout such as '30s'; None omits it. Configure transport socket timeouts separately with HttpClientOptions. |
stepstr | NoneDefault: None | Positive evaluation interval such as '30s' for range queries (default: config.default_step). On instant queries this is a VictoriaMetrics-only lookback option. |
limitint | NoneDefault: None | Nonnegative series/metadata result limit; 0 disables the limit. Query series limits are Prometheus-specific; VictoriaMetrics may ignore them. |
extra_labelstr | dict[str, str] | NoneDefault: None | VictoriaMetrics-only extra equality filters, e.g. {'tenant': 'demo'} or 'tenant=demo'. This is not a substitute for server authorization. |
extra_filtersstr | list[str] | NoneDefault: None | VictoriaMetrics-only additional selector filters, e.g. '{env="prod"}'. Query text in this client option is not sanitized by the builder. |
round_digitsint | NoneDefault: None | VictoriaMetrics response rounding precision, forwarded to the backend; no SDK numeric bound is enforced. |
nocachebool | NoneDefault: None | VictoriaMetrics-only flag to bypass query cache when True. |
tracebool | NoneDefault: None | VictoriaMetrics-only flag requesting execution trace details. |
account_idint | NoneDefault: None | Nonnegative integer VictoriaMetrics cluster tenant ID. A per-request override is rejected for non-cluster configurations. |
custom_paramsdict[str, Any] | NoneDefault: None | Additional request parameters merged after standard parameters, so duplicate keys can override them. Values and authorization remain caller-owned; no injection validation is performed. |
Returns MetricsQueryResult
query_async()Execute an instant query against the configured Prometheus or VictoriaMetrics backend. Await this asynchronous variant.
async
DatabaseClient.query_async(query: Union[str, QueryBuilder], time: Optional[TimeValue]=None, timeout: Optional[str]=None, *, step: Optional[str]=None, limit: Optional[int]=None, extra_label: Optional[Union[str, Dict[str, str], Iterable[str]]]=None, extra_filters: Optional[Union[str, Iterable[str]]]=None, round_digits: Optional[int]=None, nocache: Optional[bool]=None, trace: Optional[bool]=None, account_id: Optional[int]=None, custom_params: Optional[Dict[str, Any]]=None) -> MetricsQueryResult
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
| Parameter / type | Meaning and accepted values |
|---|---|
querystr | QueryBuilderRequired | Saved query text or a builder. Builders use the configured backend's dialect; strings are passed through without parsing or injection protection. |
timeint | float | str | datetime | NoneDefault: None | Evaluation timestamp. Numbers are Unix seconds (milliseconds when magnitude exceeds 1e10); aware datetimes and backend timestamp strings are accepted. None uses server now. |
timeoutstr | NoneDefault: None | Backend query execution timeout such as '30s'; None omits it. Configure transport socket timeouts separately with HttpClientOptions. |
stepstr | NoneDefault: None | Positive evaluation interval such as '30s' for range queries (default: config.default_step). On instant queries this is a VictoriaMetrics-only lookback option. |
limitint | NoneDefault: None | Nonnegative series/metadata result limit; 0 disables the limit. Query series limits are Prometheus-specific; VictoriaMetrics may ignore them. |
extra_labelstr | dict[str, str] | NoneDefault: None | VictoriaMetrics-only extra equality filters, e.g. {'tenant': 'demo'} or 'tenant=demo'. This is not a substitute for server authorization. |
extra_filtersstr | list[str] | NoneDefault: None | VictoriaMetrics-only additional selector filters, e.g. '{env="prod"}'. Query text in this client option is not sanitized by the builder. |
round_digitsint | NoneDefault: None | VictoriaMetrics response rounding precision, forwarded to the backend; no SDK numeric bound is enforced. |
nocachebool | NoneDefault: None | VictoriaMetrics-only flag to bypass query cache when True. |
tracebool | NoneDefault: None | VictoriaMetrics-only flag requesting execution trace details. |
account_idint | NoneDefault: None | Nonnegative integer VictoriaMetrics cluster tenant ID. A per-request override is rejected for non-cluster configurations. |
custom_paramsdict[str, Any] | NoneDefault: None | Additional request parameters merged after standard parameters, so duplicate keys can override them. Values and authorization remain caller-owned; no injection validation is performed. |
Returns MetricsQueryResult
query_range()Evaluate a query repeatedly from start to end at the requested step.
DatabaseClient.query_range(query: Union[str, QueryBuilder], start: Optional[TimeValue]=None, end: Optional[TimeValue]=None, step: Optional[str]=None, timeout: Optional[str]=None, *, limit: Optional[int]=None, extra_label: Optional[Union[str, Dict[str, str], Iterable[str]]]=None, extra_filters: Optional[Union[str, Iterable[str]]]=None, round_digits: Optional[int]=None, nocache: Optional[bool]=None, trace: Optional[bool]=None, account_id: Optional[int]=None, custom_params: Optional[Dict[str, Any]]=None) -> MetricsQueryResult
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
| Parameter / type | Meaning and accepted values |
|---|---|
querystr | QueryBuilderRequired | Saved query text or a builder. Builders use the configured backend's dialect; strings are passed through without parsing or injection protection. |
startint | float | str | datetime | NoneDefault: None | Inclusive range start or metadata lower bound. query_range defaults to one hour before end; metadata calls omit the bound when None. |
endint | float | str | datetime | NoneDefault: None | Inclusive range end or metadata upper bound. query_range defaults to now; metadata calls omit the bound when None. |
stepstr | NoneDefault: None | Positive evaluation interval such as '30s' for range queries (default: config.default_step). On instant queries this is a VictoriaMetrics-only lookback option. |
timeoutstr | NoneDefault: None | Backend query execution timeout such as '30s'; None omits it. Configure transport socket timeouts separately with HttpClientOptions. |
limitint | NoneDefault: None | Nonnegative series/metadata result limit; 0 disables the limit. Query series limits are Prometheus-specific; VictoriaMetrics may ignore them. |
extra_labelstr | dict[str, str] | NoneDefault: None | VictoriaMetrics-only extra equality filters, e.g. {'tenant': 'demo'} or 'tenant=demo'. This is not a substitute for server authorization. |
extra_filtersstr | list[str] | NoneDefault: None | VictoriaMetrics-only additional selector filters, e.g. '{env="prod"}'. Query text in this client option is not sanitized by the builder. |
round_digitsint | NoneDefault: None | VictoriaMetrics response rounding precision, forwarded to the backend; no SDK numeric bound is enforced. |
nocachebool | NoneDefault: None | VictoriaMetrics-only flag to bypass query cache when True. |
tracebool | NoneDefault: None | VictoriaMetrics-only flag requesting execution trace details. |
account_idint | NoneDefault: None | Nonnegative integer VictoriaMetrics cluster tenant ID. A per-request override is rejected for non-cluster configurations. |
custom_paramsdict[str, Any] | NoneDefault: None | Additional request parameters merged after standard parameters, so duplicate keys can override them. Values and authorization remain caller-owned; no injection validation is performed. |
Returns MetricsQueryResult
query_range_async()Evaluate a query repeatedly from start to end at the requested step. Await this asynchronous variant.
async
DatabaseClient.query_range_async(query: Union[str, QueryBuilder], start: Optional[TimeValue]=None, end: Optional[TimeValue]=None, step: Optional[str]=None, timeout: Optional[str]=None, *, limit: Optional[int]=None, extra_label: Optional[Union[str, Dict[str, str], Iterable[str]]]=None, extra_filters: Optional[Union[str, Iterable[str]]]=None, round_digits: Optional[int]=None, nocache: Optional[bool]=None, trace: Optional[bool]=None, account_id: Optional[int]=None, custom_params: Optional[Dict[str, Any]]=None) -> MetricsQueryResult
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
| Parameter / type | Meaning and accepted values |
|---|---|
querystr | QueryBuilderRequired | Saved query text or a builder. Builders use the configured backend's dialect; strings are passed through without parsing or injection protection. |
startint | float | str | datetime | NoneDefault: None | Inclusive range start or metadata lower bound. query_range defaults to one hour before end; metadata calls omit the bound when None. |
endint | float | str | datetime | NoneDefault: None | Inclusive range end or metadata upper bound. query_range defaults to now; metadata calls omit the bound when None. |
stepstr | NoneDefault: None | Positive evaluation interval such as '30s' for range queries (default: config.default_step). On instant queries this is a VictoriaMetrics-only lookback option. |
timeoutstr | NoneDefault: None | Backend query execution timeout such as '30s'; None omits it. Configure transport socket timeouts separately with HttpClientOptions. |
limitint | NoneDefault: None | Nonnegative series/metadata result limit; 0 disables the limit. Query series limits are Prometheus-specific; VictoriaMetrics may ignore them. |
extra_labelstr | dict[str, str] | NoneDefault: None | VictoriaMetrics-only extra equality filters, e.g. {'tenant': 'demo'} or 'tenant=demo'. This is not a substitute for server authorization. |
extra_filtersstr | list[str] | NoneDefault: None | VictoriaMetrics-only additional selector filters, e.g. '{env="prod"}'. Query text in this client option is not sanitized by the builder. |
round_digitsint | NoneDefault: None | VictoriaMetrics response rounding precision, forwarded to the backend; no SDK numeric bound is enforced. |
nocachebool | NoneDefault: None | VictoriaMetrics-only flag to bypass query cache when True. |
tracebool | NoneDefault: None | VictoriaMetrics-only flag requesting execution trace details. |
account_idint | NoneDefault: None | Nonnegative integer VictoriaMetrics cluster tenant ID. A per-request override is rejected for non-cluster configurations. |
custom_paramsdict[str, Any] | NoneDefault: None | Additional request parameters merged after standard parameters, so duplicate keys can override them. Values and authorization remain caller-owned; no injection validation is performed. |
Returns MetricsQueryResult
select_base_url()Return the query base URL, including the configured cluster tenant path where applicable.
DatabaseClient.select_base_url() -> str
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
No parameters.
Returns str
series()List matching series label sets through the backend metadata API.
DatabaseClient.series(match: MatchInput, start: Optional[TimeValue]=None, end: Optional[TimeValue]=None, *, limit: Optional[int]=None, account_id: Optional[int]=None, custom_params: Optional[Dict[str, Any]]=None) -> SeriesResult
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
| Parameter / type | Meaning and accepted values |
|---|---|
matchstr | QueryBuilder | Sequence[str | QueryBuilder] | NoneRequired | One or more series selectors, including lists and tuples; builders render using the backend dialect. series() requires this argument; labels/label_values may omit it. |
startint | float | str | datetime | NoneDefault: None | Inclusive range start or metadata lower bound. query_range defaults to one hour before end; metadata calls omit the bound when None. |
endint | float | str | datetime | NoneDefault: None | Inclusive range end or metadata upper bound. query_range defaults to now; metadata calls omit the bound when None. |
limitint | NoneDefault: None | Nonnegative series/metadata result limit; 0 disables the limit. Query series limits are Prometheus-specific; VictoriaMetrics may ignore them. |
account_idint | NoneDefault: None | Nonnegative integer VictoriaMetrics cluster tenant ID. A per-request override is rejected for non-cluster configurations. |
custom_paramsdict[str, Any] | NoneDefault: None | Additional request parameters merged after standard parameters, so duplicate keys can override them. Values and authorization remain caller-owned; no injection validation is performed. |
Returns SeriesResult
series_async()List matching series label sets through the backend metadata API. Await this asynchronous variant.
async
DatabaseClient.series_async(match: MatchInput, start: Optional[TimeValue]=None, end: Optional[TimeValue]=None, *, limit: Optional[int]=None, account_id: Optional[int]=None, custom_params: Optional[Dict[str, Any]]=None) -> SeriesResult
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
| Parameter / type | Meaning and accepted values |
|---|---|
matchstr | QueryBuilder | Sequence[str | QueryBuilder] | NoneRequired | One or more series selectors, including lists and tuples; builders render using the backend dialect. series() requires this argument; labels/label_values may omit it. |
startint | float | str | datetime | NoneDefault: None | Inclusive range start or metadata lower bound. query_range defaults to one hour before end; metadata calls omit the bound when None. |
endint | float | str | datetime | NoneDefault: None | Inclusive range end or metadata upper bound. query_range defaults to now; metadata calls omit the bound when None. |
limitint | NoneDefault: None | Nonnegative series/metadata result limit; 0 disables the limit. Query series limits are Prometheus-specific; VictoriaMetrics may ignore them. |
account_idint | NoneDefault: None | Nonnegative integer VictoriaMetrics cluster tenant ID. A per-request override is rejected for non-cluster configurations. |
custom_paramsdict[str, Any] | NoneDefault: None | Additional request parameters merged after standard parameters, so duplicate keys can override them. Values and authorization remain caller-owned; no injection validation is performed. |
Returns SeriesResult
storage_base_url()Return the configured storage base URL when applicable.
DatabaseClient.storage_base_url() -> str
Request methods can raise MCHTTPError, TimeoutError, ConnectionError or parameter-validation errors. Use with/async with for cleanup.
No parameters.
Returns str