Discuss with expertTry it for free
© 2026 Direct Cursus Technology L.L.C.

Reading data from Monitoring via Query connections

Written by
Updated at July 7, 2026
View in Markdown

This feature is in the Preview stage.

Monitoring allows you to collect and store metrics, as well as display them as charts on dashboards. Data sent to Monitoring includes metrics and their descriptive labels.

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

Query example for 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. Navigate to the Connections section of the Yandex Query interface and click Create new.

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

  3. In the Type dropdown, select Monitoring.

  4. In the Service account field, select an existing service account that will be used for reading metrics, or create a new one, granting it the monitoring.viewer role for the cloud.

    To use the service account on your behalf, you need the iam.serviceAccounts.user role.

  5. Click Create to create a connection.

Data model

To read metrics from Monitoring, use the following 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 whose values must be returned in separate columns.
  • <from_time>: Time interval start time in ISO 8601 format.
  • <to_time>: Time interval end time in ISO 8601 format.

This query will return all data points of all <service> metrics matching the <query> and falling within the time interval between <time_from> and <time_to>. The query result will contain the following columns:

Name Data type Description
ts Datetime Metric data point timestamp
value Double? Metric data point value corresponding to the time in the ts column
type String Metric type
labels YQL Dict Metric labels. This column will be omitted if you specified the labels parameter in the query
<label> String Metric <label> value

Note

A query with the selectors parameter has no limits on the number of metrics, but is constrained to using only a set of selectors provided 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 Valid values Default value
downsampling.disabled If true, the response data will not be downsampled true, false false
downsampling.aggregation Downsampling aggregation function MAX, MIN, SUM, AVG, LAST, COUNT AVG
downsampling.fill Data gap-filling settings NULL, NONE, PREVIOUS PREVIOUS
downsampling.grid_interval Downsampling window size, in seconds Integer 15

Metric reading example

Query example for reading 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: Monitoring connection name.
  • compute: Target service for search.
  • cpu_name as cpu, resource_id: List of labels whose values will be returned in separate columns. The system will return the cpu_name label value in the cpu column, and the resource_id in the resource_id column.
  • [2025-03-12T14:00:00Z – 2025-03-12T15:00:00Z): Search time interval.
Previous
Writing data
Next
Writing data