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

Reading data from Monitoring using Query connections

Written by
Updated at August 12, 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 permissions.

    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
    <expression>
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 to return in separate columns. You can omit the labels parameter to return all labels in yql dict format in the labels column.
  • <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.

Note

The selectors parameter has no limitations on the number of metrics but only accepts a list of selectors as input. You do not need to specify the folderId, cloudId, and service labels in the list of selectors. If you need to include query language functions, use the program parameter.

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 writing metrics

Example of a query to read metrics from Monitoring:

SELECT
    *
FROM
    `monitoring`.ydb
WITH (
    selectors = @@{name = "api.grpc.request.bytes"}@@,

    labels = "database.dedicated, database_path, api_service",

    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.
  • ydb: Required Monitoring service.
Previous
Writing data
Next
Writing data