Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Источники данныхbreadcrumb arrow InfluxDBbreadcrumb arrow Переменные шаблонов
Последнее обновление: августа 4, 2026

Переменные шаблонов InfluxDB

Вместо жёсткого прописывания таких сведений, как имена серверов, приложений и датчиков, в запросах к метрикам можно использовать переменные. Grafana отображает эти переменные в раскрывающихся списках в верхней части дашборда, чтобы вам было удобнее менять отображаемые данные. Grafana называет такие переменные переменными шаблонов (template variables).

Общую информацию о переменных см. в разделах Variables и Add and manage variables.

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

Поддерживаемые типы переменных

Тип переменной Поддерживается
Query Да
Custom Да
Data source Да
Ad-hoc filter Да (только InfluxQL)

Чтобы переключать дашборд между разными экземплярами InfluxDB, используйте переменную типа data source. Не применяйте в качестве обходного пути переменную запроса, возвращающую имена источников данных. Такие обходные решения на основе запросов могут сломаться после обновления Grafana, поскольку они зависят от внутренних идентификаторов. Подробности см. в разделе Add a data source variable.

Где можно использовать переменные

Поддержка переменных зависит от редактора запросов и режима работы:

Редактор Поддержка переменных
InfluxQL visual editor В раскрывающихся списках ваши переменные шаблонов показываются вместе со значениями из базы данных.
InfluxQL raw mode Полная поддержка.
SQL builder mode В раскрывающихся списках перечисляются только таблицы и столбцы из базы данных. Чтобы использовать переменные, переключитесь в режим code.
SQL code mode Полная поддержка. Нажмите Ctrl+Space, чтобы показать подсказки по переменным.
Flux code editor Полная поддержка.

Создание переменной запроса

Добавив переменную шаблона типа query, вы можете написать запрос для исследования метаданных InfluxDB. Такие запросы возвращают, например, имена измерений (measurement), имена ключей и значения ключей.

Дополнительные сведения см. в разделе Add a query variable.

Примеры переменных запросов InfluxQL

Чтобы создать переменную со всеми значениями тега hostname, используйте следующий запрос в поле Query:

SQL 
SHOW TAG VALUES WITH KEY = "hostname"

Можно получить имена ключей для заданного измерения:

SQL 
SHOW TAG KEYS [FROM <measurement_name>]

Можно вывести список доступных измерений:

SQL 
SHOW MEASUREMENTS

Примеры переменных запросов Flux

Для источников данных, настроенных на Flux, напишите запрос Flux, возвращающий один столбец значений:

flux 
import "influxdata/influxdb/schema"
schema.tagValues(bucket: v.defaultBucket, tag: "hostname")

Примеры переменных запросов SQL

Для источников данных, настроенных на SQL (InfluxDB 3.x), напишите SQL-запрос, возвращающий один столбец значений:

SQL 
SELECT DISTINCT hostname FROM cpu

Можно вывести список доступных таблиц:

SQL 
SHOW TABLES

Можно вывести столбцы конкретной таблицы:

SQL 
SHOW COLUMNS FROM cpu

Ограничение переменных временным диапазоном дашборда

По умолчанию запросы к метаданным, например SHOW TAG VALUES, возвращают значения за весь период хранения (retention), а не только за временной диапазон дашборда. Если узел или датчик перестал отправлять данные давно, его значения всё равно будут появляться в раскрывающемся списке переменной, пока они существуют в пределах периода хранения.

Чтобы ограничить результаты переменной временным диапазоном дашборда:

  1. Добавьте в запрос переменной условие по времени. В запросах переменных подставляются те же макросы времени, что и в обычных запросах: $timeFilter для InfluxQL, $__timeFilter(<column>) для SQL и v.timeRangeStart и v.timeRangeStop для Flux.
  2. Установите для переменной параметр Refresh в значение On time range change, чтобы значения обновлялись при изменении временного диапазона дашборда.

Пример для InfluxQL:

SQL 
SHOW TAG VALUES WITH KEY = "hostname" WHERE $timeFilter

Пример для SQL:

SQL 
SELECT DISTINCT hostname FROM cpu WHERE $__timeFilter(time)

Связывание и вложение переменных

Можно создавать вложенные переменные, которые иногда называют связанными переменными (chained variables).

Например, если у вас есть переменная с именем region, вы можете настроить переменную hosts так, чтобы она показывала только хосты из выбранного региона.

InfluxQL:

SQL 
SHOW TAG VALUES WITH KEY = "hostname"  WHERE region = '$region'

SQL:

SQL 
SELECT DISTINCT hostname FROM cpu WHERE region = '$region'

Если у вас есть переменная с именами ключей, её можно использовать в предложении GROUP BY. Это позволяет менять группировку, выбирая значения из списка переменной в верхней части дашборда.

Использование фильтров

InfluxDB поддерживает использование фильтров для InfluxQL. Они позволяют задать несколько фильтров «ключ/значение», которые Grafana автоматически применяет ко всем вашим запросам к InfluxDB. Фильтры также поддерживают выражения.

Чтобы добавить фильтры:

  1. Перейдите к дашборду, который хотите изменить, и нажмите Edit.
  2. Нажмите значок Add new element (синий плюс).
  3. Нажмите Filter and Group by.
  4. Введите Name для фильтра.
  5. Выберите вариант в раскрывающемся списке Display, чтобы задать, где на дашборде отображается фильтр.
  6. Выберите свой источник данных InfluxDB в раскрывающемся списке Data source.

Дополнительные сведения см. в документации по Filter and Group by.

Выбор синтаксиса переменных

Источник данных InfluxDB поддерживает два синтаксиса переменных для использования в поле Query:

  • $<varname> — используйте этот синтаксис для отдельных ссылок на переменную. Он не позволяет использовать переменную в середине слова или выражения.
  • ${varname} — используйте этот синтаксис, когда нужно подставить переменную в середине выражения.

Примеры для InfluxQL:

SQL 
SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^$host$/ AND $timeFilter GROUP BY time($__interval), "hostname"
SQL 
SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^${host}$/ AND $timeFilter GROUP BY time($__interval), "hostname"

Когда вы включаете параметры Multi-value или Include all value для InfluxQL, Grafana преобразует значения из простого текста в строку, совместимую с регулярными выражениями, поэтому нужно использовать =~ вместо = и обернуть переменную в регулярное выражение вида /^$host$/.

Например, если $host — переменная с несколькими значениями и вы выбрали server1 и server2, Grafana объединяет значения через |, заключает их в круглые скобки и экранирует все специальные символы. Подставленный запрос выглядит так:

SQL 
SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^(server1|server2)$/ AND $timeFilter GROUP BY time($__interval), "hostname"

Примеры для SQL:

SQL 
SELECT $__dateBin(time), mean(usage_system) FROM cpu WHERE $__timeFilter(time) AND host = '$host' GROUP BY $__dateBin(time)
SQL 
SELECT $__dateBin(time), mean(usage_system) FROM cpu WHERE $__timeFilter(time) AND host IN ($host) GROUP BY $__dateBin(time)

Когда для SQL включён параметр Multi-value, используйте оператор IN вместо =, чтобы сопоставить несколько значений.

Предотвращение нежелательного экранирования значений

Когда вы используете переменную внутри регулярного выражения или когда переменная имеет несколько значений, Grafana экранирует специальные символы в значениях, чтобы запрос оставался корректным. Если вместо этого нужно буквальное, неизменённое значение, используйте параметр формата raw:

SQL 
SELECT mean("value") FROM "requests" WHERE "path" = '${path:raw}' AND $timeFilter GROUP BY time($__interval)

Это полезно для пользовательских переменных, значения которых намеренно содержат символы, которые Grafana иначе экранировала бы. Полный список доступных параметров формата см. в разделе Advanced variable format options.

Пример дашборда с шаблонами

Пример дашборда с шаблонами см. в этом примере дашборда InfluxDB.