Документация Grafana Документация GlaberGraph Визуализация данных Панели и визуализации Запросы и преобразование данных SQL-выражения

SQL expressions

SQL-выражения — это серверные выражения, которые управляют результатами запросов к источникам данных и преобразуют их с использованием синтаксиса, похожего на MySQL. Они позволяют легко запрашивать данные и преобразовывать их после того, как источник данных их вернул, с помощью SQL — знакомого и мощного синтаксиса, который справляется со всем: от простых фильтров до очень сложных многошаговых преобразований.

В Grafana серверное выражение — это способ преобразовать данные или выполнить вычисления после того, как Grafana получила их от источника данных, но до того, как Grafana отправит их на фронтенд для визуализации. Grafana вычисляет такие выражения на сервере, а не в браузере и не в источнике данных.

Общую информацию о выражениях Grafana см. в разделе Write expression queries.

Перед началом

• Grafana включает SQL-выражения по умолчанию. Чтобы использовать их, не нужно включать функциональный переключатель или изменять конфигурацию.
• Вы должны выполнять запросы к серверному источнику данных. SQL-выражения не работают с источниками данных, которые существуют только на фронтенде.

Преобразование данных с помощью SQL-выражений

SQL-выражения позволяют:

• Формировать, преобразовывать и изменять результаты запросов, не меняя исходный запрос.
• Объединять (JOIN) данные из нескольких таблиц.
• Создавать правила оповещений или записи на основе преобразованных данных.
• Выполнять модификации наборов данных на заключительном этапе, в том числе:
  • Показывать, скрывать или переименовывать столбцы.
  • Фильтровать строки по условиям.
  • Агрегировать данные (например: сумму, среднее, количество).
• Писать подзапросы и обобщённые табличные выражения (CTE) для поддержки более сложной логики:
  • Подзапросы — это вложенные запросы, используемые для фильтрации, вычислений или преобразований.
  • CTE — это временные именованные наборы результатов, которые делают сложные запросы более читаемыми и переиспользуемыми.

Ключевая возможность SQL-выражений — объединение (JOIN) данных из нескольких таблиц. Это позволяет комбинировать и преобразовывать данные предсказуемым и удобным способом — даже для сложных сценариев. Вы можете объединять данные из множества запросов к источникам данных, с учётом ограничения на входные ячейки.

Для работы с SQL-выражениями необходимо использовать данные из серверного источника данных. В Grafana серверный источник данных — это плагин или интеграция источника данных, которые взаимодействуют с базой данных, сервисом или API через сервер Grafana, а не напрямую из браузера (фронтенда).

Источники данных, работающие только на фронтенде, например источник данных Dashboard, не поддерживаются. Для запросов, на которые вы хотите ссылаться в SQL-выражении, используйте один из совместимых источников данных, перечисленных ниже.

Совместимые источники данных

Совместимы следующие источники данных:

Полная поддержка: Grafana поддерживает все типы запросов для каждого из этих источников данных.

• Elasticsearch
• MySQL
• Loki
• Graphite
• Google Sheets
• Amazon Athena
• PostgreSQL

Частичная поддержка: Следующие источники данных поддерживаются ограниченно или условно. Некоторые поддерживают несколько типов запросов в зависимости от сервиса. Например, Azure Monitor может запрашивать несколько сервисов, каждый со своим форматом запросов. В некоторых случаях тип запроса можно переключить и внутри панели.

• InfluxDB
• Infinity
• Azure Monitor
• TestData
• Tempo
• Prometheus
• CloudWatch
• GitHub
• BigQuery

Создание SQL-выражений

Чтобы создать SQL-выражение, выполните следующие шаги:

1. Перейдите в раздел Dashboards в меню слева.
2. Выберите дашборд и откройте панель дашборда.
3. Нажмите значок с многоточием в правом верхнем углу и выберите Edit .
4. Нажмите + Expression.
5. Выберите SQL в раскрывающемся списке.

Добавив SQL-выражение, вы можете выбирать данные из других запросов к источникам данных, ссылаясь на их RefID в SQL-выражении так, как если бы это были таблицы в базе данных SQL.

Рабочий процесс построения SQL-выражений

Используйте следующий порядок действий для создания SQL-выражения:

1. Создайте базовые запросы. Создайте отдельный запрос и дайте ему осмысленное имя. Создайте запросы (A, B и т. д.), которые предоставляют данные, которые вы хотите объединить или преобразовать с помощью SQL-выражений.

2. Скройте базовые запросы. Нажмите 👁️ значок глаза рядом с каждым базовым запросом, чтобы скрыть их от визуализации. Так панель остаётся чистой, а данные всё равно доступны SQL-выражению.

3. Переключитесь на табличное представление. Установите для панели визуализацию Table, чтобы проверять и просматривать структуру и вывод SQL-выражения по мере его построения и доработки.

4. Добавьте SQL-выражение. Добавьте новый запрос и выберите SQL-выражение в качестве его типа.
   Проверьте входные данные. Начните с простых тестовых запросов, чтобы понять структуру входных фреймов.

   SQL Copy

   SELECT * FROM A LIMIT 10

   Так вы увидите доступные столбцы и примеры строк из запроса A. Повторите это для каждого входного запроса, который хотите использовать (например, SELECT * FROM B LIMIT 10).

5. Изучите свои данные. Повторите это для каждого входного запроса, чтобы понять структуру столбцов и типы данных, с которыми вы работаете.

   SQL Copy

   SELECT * FROM <B, C, D, etc> LIMIT 10

6. Составьте SQL-выражение. Поняв свои данные, напишите SQL-выражение для объединения, фильтрации или иного преобразования данных.

7. Проверяйте и повторяйте. Нажимайте Refresh каждый раз, когда обновляете SQL-запрос, чтобы пересчитать и увидеть обновлённый результат.

При выборе типа визуализации убедитесь, что SQL-выражение возвращает данные нужной формы. Например, панелям временных рядов нужен столбец с полем времени (таким как отметка времени) и столбец с числовым значением (такой как __value__). Если вывод имеет неправильную форму, ваша визуализация может отображаться пустой или не отрисоваться вообще.

Рабочий процесс SQL-выражений в Grafana имеет следующие особенности:

• Нескрытые запросы визуализируются автоматически. Если входной запрос не скрыт, Grafana попытается отрисовать его рядом с вашим SQL-выражением. Это может загромоздить вывод, особенно в табличных визуализациях.

• Результаты SQL-выражений могут быть видны не сразу. Возможно, вам придётся воспользоваться селектором фреймов данных (раскрывающийся список внизу табличной панели), чтобы переключаться между исходным запросом и результатом SQL-выражения.

• Нетабличные или неправильно сформированные данные не отобразятся в некоторых панелях. Такие визуализации, как графики или индикаторы, требуют правильно структурированных данных. Несовпадающие форматы приведут к проблемам с отрисовкой или к пропаже данных.

Редактор SQL-выражений

Редактор SQL-выражений предоставляет несколько инструментов, помогающих писать и запускать запросы.

• Run query: выполняет SQL-выражение и обновляет результат. Также можно нажать Ctrl+Enter или Cmd+Enter в macOS, когда курсор находится в редакторе.
• Format query: форматирует SQL для удобства чтения, сохраняя шаблонные переменные.
• Copy query: копирует текущий SQL в буфер обмена.

Редактор дополняет ключевые слова SQL, поддерживаемые функции и RefID ваших других запросов как имена таблиц. Автодополнение столбцов является экспериментальным и требует функционального переключателя sqlExpressionsColumnAutoComplete. Когда он включён, редактор предлагает имена столбцов, запрашивая поля у ваших источников данных.

Инспектор схемы

Когда вы включаете API сервиса запросов на своём экземпляре, редактор включает боковую панель Schema inspector. Нажмите значок глаза рядом с редактором, чтобы показать или скрыть её.

У инспектора схемы есть вкладка для каждого исходного запроса, и он перечисляет следующие сведения по каждому столбцу, чтобы вы могли ссылаться на правильные имена полей и типы при написании SQL:

• Field: имя столбца.
• Type: тип данных MySQL.
• Nullable: может ли столбец содержать значения null.
• Sample values: примеры значений из результата запроса.

Примеры SQL-выражений

1. Создайте следующий запрос Prometheus:

   promql Copy

   sum(
     rate(go_cpu_classes_gc_total_cpu_seconds_total{namespace=~".*(namespace).*5."}[$__rate_interval])
   ) by (namespace)

   Панель отобразит использование CPU сборщиком мусора Go (GC) во времени с разбивкой по namespace.

2. Добавьте SQL-выражение SELECT * from A. После добавления SQL-выражения, выбирающего данные из RefID A, Grafana преобразует его в табличный ответ:

Правила преобразования SQL

Когда вы ссылаетесь на RefID внутри инструкции SQL (например, SELECT * FROM A), система запускает отдельный процесс преобразования SQL.

Путь преобразования SQL:

• Результат запроса представляется в виде одного фрейма данных, без меток, и напрямую отображается в табличный формат.
• Если тип фрейма присутствует и является числовым, широким временным рядом или многофреймовым временным рядом (например: форматы с метками), Grafana автоматически преобразует данные в табличную структуру.

Форматы ответов источников данных

Grafana поддерживает три типа форматов ответов источников данных:

1. Single Table-like Frame (Единый таблицеподобный фрейм):
   Это данные, возвращённые в стандартной табличной структуре, которая организует все значения в строки и столбцы, подобно тому, что вы получили бы от SQL-запроса.

   • Пример: любой запрос к источнику данных SQL (например, PostgreSQL, MySQL) с форматом Table.

2. Dataplane: Time Series Format (Формат временных рядов):
   Этот формат представляет данные временных рядов с отметками времени и связанными значениями. Обычно его возвращают источники данных мониторинга.

   • Пример: Range-запросы Prometheus или Loki (запросы, возвращающие набор значений за период времени).

3. Dataplane: Numeric Long Format (Числовой длинный формат):
   Этот формат представляет мгновенные (instant) запросы метрик, возвращающие одно значение (или набор значений) в конкретный момент времени.

   • Пример: Instant-запросы Prometheus или Loki (запросы, возвращающие текущее значение метрики).

Дополнительные сведения об этих форматах см. в документации по Grafana Dataplane.

Следующие нетабличные форматы автоматически преобразуются в табличный формат (FullLong) при использовании в SQL-выражениях:

• Time Series Wide: ключи меток становятся именами столбцов.
• Time Series Multi: значения меток становятся значениями в каждой строке (или null, если метка отсутствует).
• Numeric Wide: столбец __value__ содержит числовое значение метрики.
• Numeric Multi: если отображаемое имя существует, оно появится в столбце __display_name__.

Во время преобразования:

• Ключи меток становятся именами столбцов.
• Значения меток заполняют соответствующие строки (null, если метка отсутствует).
• Столбец __value__ содержит числовое значение метрики.
• Если оно доступно, столбец __display_name__ содержит понятное человеку имя.
• Столбец __metric_name__ хранит исходный идентификатор метрики.
• Для данных временных рядов Grafana включает столбец time с отметками времени

Поддерживаемые функции

Grafana поддерживает полный список поддерживаемых ключевых слов, операторов и функций SQL в коде проверки запросов SQL-выражений.

Самый актуальный справочник по всей поддерживаемой функциональности SQL см. в определениях allowedNode и allowedFunction в кодовой базе Grafana.

Оповещения и правила записи

SQL-выражения интегрируются с оповещениями и правилами записи, позволяя определять сложные условия и метрики с помощью стандартных SQL-запросов. Система обрабатывает результаты вашего запроса и автоматически создаёт экземпляры оповещений или записанные метрики на основе возвращённой структуры данных.

Чтобы SQL-выражения корректно работали с оповещениями и правилами записи, ваш запрос должен возвращать:

• Ровно один числовой столбец — обязательно. Он содержит значение, которое запускает оповещения или записывается. Запрос завершится ошибкой, если он вернёт ни одного числового столбца или больше одного.
• Уникальные комбинации строковых столбцов — обязательно. Каждая строка должна иметь уникальную комбинацию значений строковых столбцов.
• Один или несколько строковых столбцов — необязательно. Они становятся метками для экземпляров оповещений или метрик. Примеры: service, region.

Рассмотрим следующие результаты запроса:

SQL Copy

error_count,service,region
25,auth-service,us-east
0,payment-service,us-west
15,user-service,eu-west

Этот запрос возвращает:

• числовой столбец error_count (значения: 25, 0, 15)
• строковые столбцы service и region

Для правил оповещения это создаёт три экземпляра оповещений:

• Первый экземпляр с метками {service=auth-service, region=us-east} и значением 25 (запускает оповещение — высокое число ошибок)
• Второй экземпляр с метками {service=payment-service, region=us-west} и значением 0 (без оповещения — нулевые ошибки)
• Третий экземпляр с метками {service=user-service, region=eu-west} и значением 15 (запускает оповещение — повышенное число ошибок)

Для правил записи создаётся одна метрика с тремя сериями:

• Первая серия: error_count_total{service=auth-service, region=us-east} 25
• Вторая серия: error_count_total{service=payment-service, region=us-west} 0
• Третья серия: error_count_total{service=user-service, region=eu-west} 15

Ниже приведены некоторые рекомендации для оповещений и правил записи:

• Делайте числовые значения осмысленными (например: количество ошибок, длительность запроса).
• Используйте понятные, описательные имена столбцов — они становятся вашими метками.
• Делайте строковые значения короткими и согласованными.
• Избегайте слишком большого числа уникальных комбинаций меток, так как это может привести к высокой кардинальности.
• Всегда используйте GROUP BY, чтобы избежать ошибок дублирования меток.
• Агрегируйте числовые значения логично (например: SUM(error_count)).

Известные ограничения

• Grafana поддерживает определённые источники данных. Актуальный список см. в разделе совместимые источники данных.
• SQL-выражение может ссылаться только на запросы к источникам данных. Оно не может ссылаться на другие выражения, и вы не можете использовать вывод SQL-выражения как входные данные для другого выражения.
• На одну панель или одно оповещение можно использовать только одно SQL-выражение.
• Каждый запрос SQL-выражения должен включать диапазон времени.
• SQL-выражения не поддерживаются в 32-битных сборках Grafana для ARM.
• Автодополнение доступно, но автодополнение столбцов и полей требует экспериментального функционального переключателя sqlExpressionsColumnAutoComplete.

Ограничения запросов

Grafana применяет к SQL-выражениям следующие ограничения. Администраторы могут настроить их в разделе [expressions] конфигурации Grafana. Дополнительные сведения см. в разделе Configure Grafana.

• Input cells: общее число ячеек, то есть строк, умноженных на столбцы, по всем запросам, на которые есть ссылки, не может превышать sql_expression_cell_limit. Значение по умолчанию — 100000. Если входные данные превышают это ограничение, запрос завершается ошибкой.
• Output cells: число возвращённых ячеек не может превышать sql_expression_output_cell_limit. Значение по умолчанию — 100000. Если вывод превышает это ограничение, Grafana усекает результат и возвращает предупреждение.
• Query length: текст SQL не может превышать sql_expression_query_length_limit символов. Значение по умолчанию — 10000.
• Timeout: Grafana отменяет SQL-выражение, которое выполняется дольше sql_expression_timeout. Значение по умолчанию — 10s.

Для каждого ограничения значение 0 означает отсутствие ограничения.

Ограничения регулярных выражений в SQL-выражениях

SQL-выражения выполняются на встроенном движке SQL, который вычисляет регулярные выражения с помощью стандартного пакета Go regexp, использующего синтаксис RE2, а не полноценные регулярные выражения движка SQL, совместимые с MySQL. В результате некоторые возможности регулярных выражений недоступны.

SQL-выражения, использующие функции регулярных выражений, имеют такие ограничения, как:

• Отсутствие обратных ссылок.

• Отсутствие утверждений lookahead и lookbehind.

• Различия в обработке символов возврата каретки (\r).

Возможны и другие незначительные различия.

Изменения схемы и отсутствующие данные

У SQL-выражений есть известные ограничения, из-за которых запросы могут завершаться ошибкой или возвращать неожиданные результаты. Эти ограничения присущи тому, как работает функция, поэтому учитывайте их при построении запросов.

Эти ограничения затрагивают следующие ситуации:

• Ответы с ошибкой: когда запрос к источнику данных возвращает ошибку, SQL-выражения не могут интерпретировать результат.

• Ответы без данных: если запрос не возвращает ни одной строки, движок SQL-выражений не может определить схему.

• Ответы с динамической схемой: если набор столбцов или меток меняется между выполнениями запроса, SQL-выражения могут завершиться ошибкой, так как они трактуют изменения столбцов как изменения схемы.

SQL-выражения работают на встроенном движке SQL, который рассматривает каждый результат запроса как таблицу. Grafana выводит схему этой таблицы из столбцов, которые возвращает нижележащий источник данных.

В отличие от традиционных баз данных SQL, где схемы обычно фиксированы, многие источники данных Grafana (например, Prometheus) могут возвращать результаты с меняющимися наборами меток или вообще без данных.

Когда это происходит:

• Отсутствующий столбец выглядит для движка SQL так, как будто его не существует.
• Полностью пустой результат не предоставляет схемы для последующих операций SQL.
• Ответы с ошибкой нарушают предположение о том, что запрос возвращает табличные данные.

В результате SQL-выражения не могут корректно обрабатывать изменения схемы или ситуации отсутствия данных, так как эти случаи нарушают статичную модель схемы, на которую опирается SQL.

Обходные пути

Вы можете смягчить эти проблемы следующими способами:

• Избегайте SELECT *: явно выбирайте только те столбцы, которые, как вы ожидаете, существуют.

• Обеспечьте согласованную схему: если возможно, настройте запрос так, чтобы он всегда возвращал столбцы, даже когда данных нет.

Пример: обработка отсутствия данных в Prometheus

При объединении результатов одного и того же запроса Prometheus из разных экземпляров источников данных можно использовать такой подход:

SQL Copy

-- Prometheus query
sum by (cluster) (up{job=~".*zruler.*"})
or on (cluster) (
  (0/0) *
  (
    label_replace(vector(1), "cluster", "fake", "", "")
  )
)

-- SQL expression
SELECT
    COALESCE(a.time, b.time) AS time,
    COALESCE(a.cluster, b.cluster) AS cluster,
    COALESCE(a.up, 0) + COALESCE(b.up, 0) AS unified_up
FROM (
    SELECT time, cluster, __value__ AS up
    FROM A
    WHERE cluster != 'fake'
    ORDER BY time
    LIMIT 5
) a
FULL OUTER JOIN (
    SELECT time, cluster, __value__ AS up
    FROM B
    WHERE cluster != 'fake'
    ORDER BY time
    LIMIT 5
) b ON a.time = b.time;

Такой подход гарантирует, что схема существует, даже когда один из запросов не возвращает данных.

Интеграция с Grafana Assistant

Grafana Assistant привносит помощь на базе ИИ в ваш рабочий процесс работы с SQL-выражениями. Assistant знает SQL-выражения, поэтому может объяснить запрос, исправить синтаксические ошибки и предложить улучшения, используя правильный синтаксис диалекта MySQL, ссылки на таблицы и соглашения о столбцах.

Вы также можете попросить Assistant построить панель с помощью естественного языка. Когда вы просите его объединить или сопоставить данные из нескольких запросов, он предпочитает SQL-выражения преобразованиям соединения и записывает SQL-выражение прямо в вашу панель.

Когда Grafana Assistant доступен на вашем экземпляре, редактор SQL-выражений показывает кнопки Assistant справа от кнопки Run query. Когда вы используете кнопку, Assistant открывается на боковой панели, и ваш SQL-запрос, все ошибки запроса и метаданные столбцов вашей схемы уже включены в контекст, так что он может ссылаться на фактические имена и типы полей в ваших данных. Оттуда вы получаете полный опыт работы с Assistant, включая уточняющие вопросы, историю переписки и доступ к встроенным инструментам Assistant.

• Explain query: описывает, что делает ваш запрос, включая его интерпретированное значение.
• Improve query: предлагает улучшения производительности, надёжности и читаемости, а также исправляет синтаксические ошибки. Если вы ещё не написали запрос, эта кнопка отображается как Generate suggestion и предлагает стартовый запрос, например соединение, агрегацию, фильтр, перцентиль или оконную функцию по времени, используя ваши доступные запросы.