Документация Grafana Документация GlaberGraph Источники данных PostgreSQL Редактор запросов

Редактор запросов PostgreSQL

Редактор запросов PostgreSQL позволяет создавать и выполнять запросы к вашему источнику данных. Общие концепции редактора запросов и преобразования данных см. в разделе Запрос и преобразование данных.

Вы можете открыть редактор запросов PostgreSQL со страницы Explore или с панели дашборда. Нажмите многоточие в правом верхнем углу панели и выберите Edit.

Компоненты редактора запросов PostgreSQL

Редактор запросов PostgreSQL имеет два режима: Builder и Code.

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

Режим PostgreSQL Builder

Следующие компоненты помогают построить запрос PostgreSQL:

• Format — выберите формат результата запроса в раскрывающемся списке. По умолчанию — Table. Если вы используете формат Time series, один из столбцов должен быть time. Дополнительную информацию см. в разделе Запросы временных рядов.
• Table — выберите таблицу в раскрывающемся списке. Таблицы соответствуют выбранной базе данных.
• Data operations — Необязательно. Выберите агрегацию в раскрывающемся списке. Вы можете добавить несколько операций с данными, нажав знак +. Нажмите знак X, чтобы удалить операции с данными.
• Column — выберите столбец, по которому следует выполнить агрегацию.
• Alias — Необязательно. Добавьте псевдоним из раскрывающегося списка. Вы также можете добавить свой собственный псевдоним, введя его в поле и нажав Enter. Удалите псевдоним, нажав X.
• Filter — переключатель для добавления фильтров.
• Filter by column value — Необязательно. Если вы включите Filter, вы можете добавить столбец для фильтрации из раскрывающегося списка. Чтобы фильтровать по нескольким столбцам, нажмите знак + справа от раскрывающегося списка условий. Выберите оператор в раскрывающемся списке рядом с условием. Когда добавлено несколько фильтров, вы можете добавить оператор AND, чтобы отобразить все истинные условия, или оператор OR, чтобы отобразить любые истинные условия. Используйте второй раскрывающийся список, чтобы выбрать значение фильтра. Чтобы удалить фильтр, нажмите X рядом с раскрывающимся списком этого фильтра. После выбора столбца типа даты вы можете выбрать Macros в списке операторов и выбрать timeFilter, чтобы добавить макрос $__timeFilter в запрос с выбранным столбцом даты.
• Group — переключатель для добавления Group by column.
• Group by column — выберите столбец для группировки в раскрывающемся списке. Нажмите знак +, чтобы группировать по нескольким столбцам. Нажмите X, чтобы удалить столбец.
• Order — переключатель для добавления инструкции ORDER BY.
• Order by — выберите столбец для сортировки в раскрывающемся списке. Выберите порядок по возрастанию (ASC) или по убыванию (DESC).
• Limit — вы можете добавить необязательное ограничение на количество извлекаемых результатов. По умолчанию 50.
• Preview — переключатель для предпросмотра SQL-запроса, сгенерированного конструктором запросов. Предпросмотр включён по умолчанию.

Режим PostgreSQL Code

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

Выберите Table или Time Series в качестве формата. Нажмите {} в правом нижнем углу, чтобы отформатировать запрос. Нажмите стрелку вниз, чтобы развернуть редактор режима Code. CTRL/CMD + Return служит сочетанием клавиш для выполнения запроса.

Макросы

Вы можете добавлять макросы в свои запросы, чтобы упростить синтаксис и включить динамические элементы, такие как фильтры диапазона дат.

Grafana разворачивает макросы в нативный PostgreSQL SQL перед выполнением запроса. Когда включено расширение TimescaleDB, $__timeGroup и $__timeGroupAlias используют time_bucket() для более эффективной группировки.

Макросы временных рядов

Макросы UNIX epoch

Переменные интервалов

В дополнение к перечисленным макросам перед выполнением запроса заменяются следующие переменные интервалов Grafana:

Вы можете задать нижнюю границу для этих переменных с помощью опции Min time interval в конфигурации источника данных или в параметрах запроса панели.

Поведение макросов

Учитывайте следующее поведение при использовании макросов:

• Удаление комментариев: Grafana удаляет SQL-комментарии (строчные комментарии -- и блочные комментарии /* */) перед разворачиванием макросов. Макросы, размещённые внутри комментариев, не разворачиваются.
• Режим TimescaleDB: Когда в конфигурации источника данных включён переключатель TimescaleDB, $__timeGroup и $__timeGroupAlias используют функцию time_bucket() PostgreSQL вместо floor(extract(epoch ...)).
• Шаблон с завершающей запятой: Вызов $__timeGroup(...), за которым сразу следует запятая (,), автоматически рассматривается как $__timeGroupAlias(...), добавляя псевдоним AS "time". Это унаследованное удобство. Для ясности используйте $__timeGroupAlias явно.
• Просмотр развёрнутого SQL: Чтобы увидеть итоговый SQL после разворачивания макросов, откройте Query inspector на панели и проверьте запрос, отправленный в базу данных.

Табличные запросы

Если опция Format установлена в Table, вы можете выполнять практически любой тип SQL-запроса. Панель Table автоматически отображает результирующие столбцы и строки вашего запроса.

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

SQL Copy

SELECT
  title as "Title",
  "user".login as "Created By",
  dashboard.created as "Created On"
FROM dashboard
INNER JOIN "user" on "user".id = dashboard.created_by
WHERE $__timeFilter(dashboard.created)

Вы можете использовать переменные шаблонов в запросах для создания динамических, многократно используемых дашбордов. Например, чтобы отфильтровать по переменной с именем hostname:

SQL Copy

SELECT
  $__time("time_date_time"),
  value_double AS value,
  hostname
FROM test_data
WHERE
  $__timeFilter("time_date_time")
  AND hostname IN($hostname)
ORDER BY time

Дополнительную информацию о создании и использовании переменных шаблонов с PostgreSQL см. в разделе Переменные шаблонов PostgreSQL.

Табличный запрос со столбцами диапазона времени

Табличные запросы поддерживают столбец timeend в дополнение к столбцу time. Когда присутствуют оба, Grafana рассматривает строку как диапазон времени, а не как одну точку. Это полезно для отображения событий с длительностью, таких как окна обслуживания или развёртывания.

SQL Copy

SELECT
  start_time AS "time",
  end_time AS "timeend",
  description,
  status
FROM maintenance_windows
WHERE $__timeFilter(start_time)

Запросы временных рядов

Установите опцию Format в Time series, чтобы создавать и выполнять запросы временных рядов.

Примеры в этом разделе относятся к данным в следующей таблице:

text Copy

+---------------------+--------------+---------------------+----------+
| time_date_time      | value_double | CreatedAt           | hostname |
+---------------------+--------------+---------------------+----------+
| 2020-01-02 03:05:00 | 3.0          | 2020-01-02 03:05:00 | 10.0.1.1 |
| 2020-01-02 03:06:00 | 4.0          | 2020-01-02 03:06:00 | 10.0.1.2 |
| 2020-01-02 03:10:00 | 6.0          | 2020-01-02 03:10:00 | 10.0.1.1 |
| 2020-01-02 03:11:00 | 7.0          | 2020-01-02 03:11:00 | 10.0.1.2 |
| 2020-01-02 03:20:00 | 5.0          | 2020-01-02 03:20:00 | 10.0.1.2 |
+---------------------+--------------+---------------------+----------+

Результаты запросов временных рядов возвращаются в широком формате data frame. В результате запроса data frame любой столбец, кроме столбцов времени или строкового типа, преобразуется в поля значений. Строковые столбцы становятся метками полей.

Определение столбца метрики

Плагин PostgreSQL определяет столбцы строкового типа (text, varchar, char, bpchar) как столбцы меток, которые разделяют результат на несколько рядов. Числовые столбцы и столбцы времени становятся полями значений.

Заполнение пропущенных точек временных рядов

При использовании $__timeGroup или $__unixEpochGroup с параметром заполнения (третий аргумент) Grafana заполняет пробелы в данных вашего временного ряда. Это полезно, когда ваши данные имеют нерегулярные интервалы или пропущенные точки данных. Заполнение работает только с запросами формата временных рядов.

Доступны следующие режимы заполнения:

Например, $__timeGroupAlias("CreatedAt",'5m', 0) группирует данные в 5-минутные интервалы и заполняет любые пробелы значением 0.

Ограничения на количество строк

Grafana применяет серверное ограничение на количество строк в результатах запроса, чтобы защититься от чрезмерного использования памяти. Если ваш запрос возвращает больше строк, чем лимит, результат усекается. Чтобы уменьшить количество возвращаемых строк, сузьте диапазон времени дашборда, увеличьте интервал $__timeGroup или добавьте предложение LIMIT в ваш запрос.

Пример со столбцом metric:

SQL Copy

SELECT
  $__timeGroupAlias("time_date_time",'5m'),
  min("value_double"),
  'min' as metric
FROM test_data
WHERE $__timeFilter("time_date_time")
GROUP BY time
ORDER BY time

Результат data frame:

text Copy

+---------------------+-----------------+
| Name: time          | Name: min       |
| Labels:             | Labels:         |
| Type: []time.Time   | Type: []float64 |
+---------------------+-----------------+
| 2020-01-02 03:05:00 | 3               |
| 2020-01-02 03:10:00 | 6               |
+---------------------+-----------------+

Чтобы настроить форматирование имени ряда по умолчанию, см. Определения стандартных опций.

Далее приведены примеры запросов временных рядов.

Пример без группировки (сырые точки):

Чтобы вернуть сырые точки времени и значений без группировки, используйте $__time, чтобы задать псевдоним вашему столбцу даты/времени как time:

SQL Copy

SELECT
  $__time("time_date_time"),
  "value_double" as value
FROM test_data
WHERE $__timeFilter("time_date_time")
ORDER BY time

Пример использования параметра заполнения в макросе $__timeGroupAlias для преобразования значений null в ноль:

SQL Copy

SELECT
  $__timeGroupAlias("CreatedAt",'5m',0),
  sum(value) as value,
  hostname
FROM test_data
WHERE
  $__timeFilter("CreatedAt")
GROUP BY time, hostname
ORDER BY time

Основываясь на результате data frame в следующем примере, панель временных рядов создаёт два ряда с именами value 10.0.1.1 и value 10.0.1.2. Чтобы отобразить имена рядов как 10.0.1.1 и 10.0.1.2, используйте значение отображения Определения стандартных опций ${__field.labels.hostname}.

Результат data frame:

text Copy

+---------------------+---------------------------+---------------------------+
| Name: time          | Name: value               | Name: value               |
| Labels:             | Labels: hostname=10.0.1.1 | Labels: hostname=10.0.1.2 |
| Type: []time.Time   | Type: []float64           | Type: []float64           |
+---------------------+---------------------------+---------------------------+
| 2020-01-02 03:05:00 | 3                         | 4                         |
| 2020-01-02 03:10:00 | 6                         | 7                         |
+---------------------+---------------------------+---------------------------+

Пример с несколькими столбцами:

SQL Copy

SELECT
  $__timeGroupAlias("time_date_time",'5m'),
  min("value_double") as "min_value",
  max("value_double") as "max_value"
FROM test_data
WHERE $__timeFilter("time_date_time")
GROUP BY time
ORDER BY time

Результат data frame:

text Copy

+---------------------+-----------------+-----------------+
| Name: time          | Name: min_value | Name: max_value |
| Labels:             | Labels:         | Labels:         |
| Type: []time.Time   | Type: []float64 | Type: []float64 |
+---------------------+-----------------+-----------------+
| 2020-01-02 03:04:00 | 3               | 4               |
| 2020-01-02 03:05:00 | 6               | 7               |
+---------------------+-----------------+-----------------+

Пример со столбцом времени UNIX epoch:

Когда ваш столбец времени хранит UNIX epoch (секунды), используйте $__timeEpoch, чтобы задать ему псевдоним time, и $__unixEpochFilter в предложении WHERE:

SQL Copy

SELECT
  $__timeEpoch(epoch_seconds_column),
  value_column as value
FROM my_table
WHERE $__unixEpochFilter(epoch_seconds_column)
ORDER BY time

Для сгруппированных временных рядов со столбцами epoch используйте $__unixEpochGroupAlias и $__unixEpochFilter. Подробности см. в таблице Макросы.

Запросы EXPLAIN

Вы можете выполнять запросы EXPLAIN и EXPLAIN ANALYZE в режиме Code, чтобы изучить планы выполнения запросов. Результаты возвращаются в виде таблицы, что полезно для диагностики медленных запросов прямо в Grafana.

SQL Copy

EXPLAIN ANALYZE
SELECT
  $__timeGroupAlias("time_date_time", '5m'),
  avg("value_double") AS value
FROM test_data
WHERE $__timeFilter("time_date_time")
GROUP BY time
ORDER BY time

Макросы Grafana разворачиваются перед выполнением запроса, поэтому вы можете использовать $__timeFilter и другие макросы в ваших запросах EXPLAIN, чтобы увидеть фактический план выполнения для диапазона времени дашборда. Установите Format в Table, чтобы отобразить вывод плана.

Дальнейшие шаги

• Используйте переменные шаблонов для создания динамических, многократно используемых дашбордов.
• Добавьте аннотации из PostgreSQL, чтобы накладывать события на ваши панели.
• Настройте алертинг, чтобы получать уведомления, когда метрики пересекают пороговые значения (только формат временных рядов).
• Устраняйте проблемы, если вы сталкиваетесь с проблемами с запросами.