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

Переменные шаблонов Microsoft SQL Server

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

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

Введение в шаблонизацию и переменные шаблонов см. в разделах Templating и Add and manage variables.

Переменная запроса

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

Например, следующий запрос возвращает все значения из столбца hostname:

SQL 
SELECT hostname FROM host

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

SQL 
SELECT [host].[hostname], [other_host].[hostname2] FROM host JOIN other_host ON [host].[city] = [other_host].[city]

Также можно создать переменную «ключ/значение» с помощью запроса, возвращающего два столбца с именами __text и __value.

  • Столбец __text задаёт метку, отображаемую в раскрывающемся списке.

  • Столбец __value задаёт значение, передаваемое в запросы панелей.

Это удобно, когда нужно показать понятную пользователю метку (например, имя хоста), но использовать другое нижележащее значение (например, идентификатор).

Учтите, что значения в столбце _text должны быть уникальными. При наличии дубликатов Grafana использует только первую совпавшую запись.

SQL 
SELECT hostname __text, id __value FROM host

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

SQL 
SELECT hostname FROM host WHERE region IN ($region)

Использование переменных в запросах

Grafana автоматически заключает значения переменных шаблонов в кавычки только тогда, когда переменная шаблона является multi-value.

При использовании многовыбираемой переменной применяйте оператор сравнения IN вместо =, чтобы сопоставлять несколько значений.

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

  • Синтаксис $<varname>

Пример с переменной шаблона с именем hostname:

SQL 
SELECT
  atimestamp time,
  aint value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in($hostname)
ORDER BY atimestamp
  • Синтаксис [[varname]]

Пример с переменной шаблона с именем hostname:

SQL 
SELECT
  atimestamp as time,
  aint as value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
ORDER BY atimestamp

Форматирование переменных для SQL-запросов

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

Использование sqlstring для безопасной интерполяции одного значения

Формат ${var:sqlstring} заключает значение переменной в одинарные кавычки и экранирует все внутренние одинарные кавычки. Это рекомендуемый подход для многовыбираемых переменных, используемых в предложениях WHERE:

SQL 
SELECT * FROM events
WHERE hostname = ${hostname:sqlstring}

Если hostname имеет значение server01, это разворачивается в:

SQL 
SELECT * FROM events
WHERE hostname = 'server01'

Caution

Не заключайте переменные в кавычки вручную (например, '${var}'). Начиная с Grafana v11.3 многовыбираемые переменные автоматически заключаются в кавычки при использовании с оператором IN. Добавление кавычек вручную приводит к двойному заключению в кавычки (например, ''value''), что ломает запросы.

Форматирование многовыбираемых переменных

Когда переменная допускает несколько вариантов выбора, Grafana предоставляет несколько вариантов форматирования:

Формат Синтаксис Результат для выбора a, b Вариант использования
Default (auto-quoted) $var или ${var} 'a','b' Предложения IN (рекомендуется)
sqlstring ${var:sqlstring} 'a' (только одно значение) Сравнения на равенство
csv ${var:csv} a,b Списки без кавычек
singlequote ${var:singlequote} 'a','b' Явное заключение в одинарные кавычки
doublequote ${var:doublequote} "a","b" Заключение идентификаторов в кавычки MSSQL
pipe ${var:pipe} a|b Шаблоны регулярных выражений
raw ${var:raw} a,b Без экранирования (использовать осторожно)

Для многовыбираемых переменных в предложениях WHERE SQL обычно правильно использовать формат по умолчанию вместе с IN:

SQL 
SELECT * FROM events
WHERE hostname IN ($hostname)

Если у hostname выбраны значения server01 и server02, это разворачивается в:

SQL 
SELECT * FROM events
WHERE hostname IN ('server01','server02')

Отключение заключения в кавычки для многовыбираемых переменных

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

text 
${servers:csv}

Это выводит значения в виде списка, разделённого запятыми, без кавычек. Используйте это только тогда, когда вы сами обрабатываете кавычки или когда значения числовые.

Полный список вариантов форматирования см. в разделе Advanced variable format options.

Работа с опцией “All” в SQL-запросах

Когда переменная включает опцию All (включённую в настройках переменной), нужно обрабатывать случай, когда пользователь выбирает “All”, иначе, чем отдельные варианты.

Шаблон: пользовательское значение “All” с LIKE

Задайте в настройках переменной поле Custom all value равным %, а затем используйте LIKE в запросе:

SQL 
SELECT * FROM events
WHERE hostname LIKE ${hostname:sqlstring}

Когда пользователь выбирает “All”, hostname принимает значение %, и LIKE '%' сопоставляется со всеми строками. Когда выбрано конкретное значение, LIKE 'server01' сопоставляется только с ним.

Шаблон: условное предложение WHERE с “All”

Для предложений IN, где % не работает, используйте условный подход. Задайте Custom all value равным ALL, а затем напишите:

SQL 
SELECT * FROM events
WHERE (
  ${hostname:raw} = 'ALL'
  OR hostname IN ($hostname)
)

Когда пользователь выбирает “All”, первое условие истинно, и сопоставляются все строки. Когда выбраны конкретные значения, предложение IN фильтрует как обычно.

Шаблон: связанные переменные с “All”

Когда есть связанные (зависимые) переменные и родительская использует “All”, примените тот же шаблон. Например, если region влияет на hostname:

Запрос переменной для hostname:

SQL 
SELECT hostname FROM host
WHERE (${region:raw} = 'ALL' OR region IN ($region))

Запрос панели:

SQL 
SELECT $__timeGroupAlias(time, '5m'), COUNT(*) as count
FROM events
WHERE $__timeFilter(time)
  AND (${region:raw} = 'ALL' OR region IN ($region))
  AND (${hostname:raw} = 'ALL' OR hostname IN ($hostname))
GROUP BY $__timeGroup(time, '5m')
ORDER BY 1

Условные предложения SQL

В Grafana нет встроенной поддержки условного исключения целых предложений WHERE в зависимости от выбора переменной. Используйте один из этих шаблонов для условной фильтрации.

Шаблон: всегда истинное условие

Используйте условие, которое вычисляется как истинное, когда переменную следует игнорировать:

SQL 
SELECT * FROM events
WHERE $__timeFilter(time)
  AND (${env:raw} = 'ALL' OR environment IN ($env))
  AND (${sev:raw} = 'ALL' OR severity IN ($sev))

Шаблон: выражение CASE для необязательных фильтров

Для более сложных сценариев используйте выражение CASE:

SQL 
SELECT * FROM events
WHERE $__timeFilter(time)
  AND 1 = CASE
    WHEN ${hostname:raw} = 'ALL' THEN 1
    WHEN hostname IN ($hostname) THEN 1
    ELSE 0
  END

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

Учитывайте следующее поведение при использовании переменных шаблонов с Microsoft SQL Server.

Автоматическое заключение в кавычки у многовыбираемых переменных

Начиная с Grafana v11.3 многовыбираемые переменные, используемые с оператором IN, автоматически заключаются в кавычки. Если вы раньше писали WHERE col IN ('${var}') с кавычками вручную, уберите кавычки вручную и вместо этого используйте WHERE col IN ($var).

Комментарии внутри строковых литералов

Парсер SQL-запросов Grafana удаляет SQL-комментарии (-- и /* */) перед интерполяцией макросов. В некоторых случаях -- внутри строкового литерала в кавычках может быть неверно истолковано как комментарий. Если ваш запрос содержит строки с --, проверьте корректность разворачивания запроса, нажав Generated SQL после выполнения запроса.

Переменные в запросах алертинга

Переменные шаблонов не поддерживаются в запросах алертинга. Grafana вычисляет правила алертинга на бэкенде без контекста дашборда. Если ваш запрос дашборда использует переменные, создайте отдельный запрос алертинга с жёстко заданными значениями. Дополнительные сведения см. в разделе Microsoft SQL Server alerting.