Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Reading data from Monitoring using Query connections

Written by
Updated at October 20, 2025

Monitoring allows you to collect and store metrics and display them as charts on dashboards. Data sent to Monitoring consists of measured values (metrics) and labels that describe them.

For example, to track the number of application failures, you can use the failure count per time interval as a metric. Data describing a failure, e.g., a host name or application version, serves as labels. The Monitoring interface allows you to aggregate metrics by label.

Example of reading metrics from Monitoring:

SELECT
    *
FROM
    monitoring.ydb
WITH (
    program = @@max{method="DescribeTable"}@@,

    from = "2025-03-12T14:00:00Z",
    to = "2025-03-12T15:00:00Z"
);

Setting up a connection

To read metrics from Monitoring, do the following:

  1. Go to Connections in the Yandex Query interface and click Create new.

  2. In the window that opens, specify a name for a connection to Monitoring in the Name field.

  3. In the drop-down list under Type, select Monitoring.

  4. In the Service account field, select a service account for metric reads or create a new one with the monitoring.viewer role for the cloud.

    To use a service account, the iam.serviceAccounts.user role is required.

  5. Click Create to create a connection.

Data model

To read metrics from Monitoring, use this SQL statement:

SELECT
    *
FROM
    <connection>.<service>
WITH (
    (selectors|program) = "<query>",
    labels = "<labels>",
    from = "<from_time>",
    to = "<to_time>",
    <downsampling_parameters>
)

Where:

  • <connection>: Name of the Monitoring connection created in the previous step.
  • <service>: Monitoring.
  • <query>: Query in the Monitoring query language.
  • <labels>: List of label names for which values must be returned in separate columns.
  • <from_time>: Left boundary of the required time interval in ISO 8601 format.
  • <to_time>: Right boundary of the required time interval in ISO 8601 format.

This query will return all <service> metric points meeting the <query> criteria and within the [<time_from>, <time_to>) interval. The query result will include the following columns:

Name Data type Description
ts Datetime Time of the metric point
value Double? Metric point value mapped to the time value from ts
type String Type of the metric with the point
labels YQL Dict Labels of the metric with the point. This column will be missing if you specified the labels parameter in the query.
<label> String <label> value of the metric with the point

Note

A query with the selectors parameter has no limitations on the number of metrics but only accepts a list of selectors as input. If you need to include query language functions, use the program parameter.

Note

You do not need to specify the folderId and service labels in the list of selectors.

Query parameter format

Parameter name Format Example
selectors ["sensor_name"]{[label_name1 = "label_value1", label_name2 = "label_value2", ...]} {name = "api.grpc.request.bytes", method="DescribeTable"}
program Query in the Monitoring query language series_sum{method="DescribeTable"}
labels "label1 [as alias1], label2 [as alias2], ..." "database.dedicated as db, database_path, api_service as api"
from / to Time in ISO 8601 format "2025-05-20T12:00:00Z"

Downsampling parameters

Yandex Query supports the following downsampling parameters:

Parameter name Description Possible values Default value
downsampling.disabled If true, indicates that the response data will not be downsampled true, false false
downsampling.aggregation Downsampling aggregation function MAX, MIN, SUM, AVG, LAST, COUNT AVG
downsampling.fill Parameters for filling in missing data NULL, NONE, PREVIOUS PREVIOUS
downsampling.grid_interval Downsampling time window, i.e., grid, size in seconds Integer 15

Example of reading metrics

Example of a query to read metrics from Monitoring:

SELECT
    *
FROM
    monitoring.compute
WITH (
    selectors = @@"cpu_utilization"{resource_type="vm"}@@,

    labels = "cpu_name as cpu, resource_id",

    from = "2025-03-12T14:00:00Z",
    to = "2025-03-12T15:00:00Z",

    `downsampling.aggregation` = "AVG",
    `downsampling.fill` = "PREVIOUS",
    `downsampling.grid_interval` = "15"
);

Where:

  • monitoring: Name of the connection to Monitoring.
  • compute: Service to search within.
  • cpu_name as cpu, resource_id: List of labels to return values for in separate columns. The value of the cpu_name label will be returned in the cpu column, and the resource_id value, in the resource_id column.
  • [2025-03-12T14:00:00Z – 2025-03-12T15:00:00Z): Time interval for the search.
Previous
Writing data
Next
Writing data