Microsoft SQL Server 템플릿 변수

Microsoft SQL Server 템플릿 변수 (Template variables)

지표 쿼리에 서버, 애플리케이션, 센서 이름 같은 세부 정보를 하드코딩하는 대신 변수를 사용할 수 있어요. Grafana는 이 변수를 대시보드 상단의 드롭다운 선택 상자에 표시해 대시보드에 표시되는 데이터를 바꿀 수 있게 해줘요. Grafana는 이러한 변수를 템플릿 변수라고 부러요.

출처: Microsoft SQL Server template variables

본문

Grafana에서 변수 사용 일반 정보는 Add variables를 참고하세요. 템플릿과 템플릿 변수 소개는 Templating과 Add and manage variables를 참고하세요.

쿼리 변수

Grafana의 쿼리 변수는 쿼리를 사용해 데이터 소스에서 동적으로 값을 검색해요. 쿼리 변수로 measurement 이름, 키 이름, 키 값 같은 값을 반환하는 SQL 쿼리를 작성하고 이를 드롭다운 select 상자에 표시할 수 있어요.

예를 들어 다음 쿼리는 hostname 열의 모든 값을 반환해요.

SELECT hostname FROM host

쿼리는 여러 열을 반환할 수 있고 Grafana가 그 열의 값으로 목록을 자동 생성해요. 예를 들어 다음 쿼리는 hostname과 hostname2 열의 값을 모두 반환하며, 둘 다 변수의 드롭다운 목록에 포함돼요.

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

__text와 __value라는 두 열을 반환하는 쿼리로 키/값 변수를 만들 수도 있어요.

__text 열은 드롭다운에 표시되는 라벨을 정의해요.
__value 열은 패널 쿼리에 전달되는 값을 정의해요.

이는 사용자 친화적인 라벨(호스트 이름 같은)을 표시하면서 다른 기본 값(ID 같은)을 사용하려 할 때 유용해요. _text 열의 값은 고유해야 한다는 점을 알아두세요. 중복이 있으면 Grafana는 첫 번째 일치 항목만 사용해요.

SELECT hostname __text, id __value FROM host

하나의 변수가 다른 변수의 값에 의존하는 중첩 변수도 만들 수 있어요. 예를 들어 region 변수가 있다면 hosts 변수를 선택한 region의 호스트만 표시하도록 구성할 수 있어요. region이 multi-value 변수라면 여러 선택 값을 일치시키려면 = 대신 IN 연산자를 사용해요.

SELECT hostname FROM host WHERE region IN ($region)

쿼리에서 변수 사용

Grafana는 템플릿 변수가 multi-value일 때만 템플릿 변수 값을 자동으로 따옴표 처리해요. multi-value 변수를 사용할 때는 여러 값과 일치시키려면 = 대신 IN 비교 연산자를 사용해요.

Grafana는 쿼리에서 변수를 사용하는 두 가지 문법을 지원해요.

$<varname> 문법

hostname 템플릿 변수 예시:

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

[[varname]] 문법

hostname 템플릿 변수 예시:

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 절에서 사용하는 단일 값 변수에 권장되는 방법이에요.

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

hostname이 server01로 설정되면 다음과 같이 확장돼요.

SELECT * FROM events
WHERE hostname = 'server01'

주의: 변수를 수동으로 따옴표로 감싸지 마세요(예: '${var}'). Grafana v11.3부터 multi-value 변수는 IN 연산자와 함께 사용될 때 자동으로 따옴표 처리돼요. 수동으로 따옴표를 추가하면 이중 따옴표(''value'')가 되어 쿼리가 깨져요.

multi-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`	이스케이프 없음(주의해서 사용)

SQL WHERE 절의 multi-value 변수에는 IN과 함께 기본 서식이 일반적으로 올바르다.

SELECT * FROM events
WHERE hostname IN ($hostname)

hostname에 server01과 server02 값이 선택돼 있으면 다음과 같이 확장돼요.

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

multi-value 변수 따옴표 비활성화

multi-value 변수를 자동 따옴표 없이 출력하려면 csv 형식을 사용해요.

${servers:csv}

이는 값을 따옴표 없는 쉼표 구분 목록으로 출력해요. 직접 따옴표를 처리하거나 값이 숫자일 때만 사용해요. 서식 옵션 전체 목록은 Advanced variable format options을 참고하세요.

SQL 쿼리에서 "All" 옵션 처리

변수에 All 옵션(변수 설정에서 활성화)이 포함되면 사용자가 개별 선택과 다르게 "All"을 선택하는 경우를 처리해야 해요.

패턴: `LIKE`와 함께 커스텀 "All" 값 사용

변수 설정의 Custom all value 필드를 %로 설정한 다음 쿼리에서 LIKE를 사용해요.

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

사용자가 "All"을 선택하면 hostname이 %로 해석되고, LIKE '%'가 모든 행과 일치해요. 특정 값을 선택하면 LIKE 'server01'이 그 값만 일치시켜요.

패턴: "All"이 있는 조건부 `WHERE` 절

%가 작동하지 않는 IN 절에는 조건부 접근을 사용해요. Custom all value를 ALL로 설정한 다음 작성해요.

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

사용자가 "All"을 선택하면 첫 번째 조건이 참이어서 모든 행이 일치해요. 특정 값을 선택하면 IN 절이 정상적으로 필터링해요.

패턴: "All"이 있는 체인 변수

체인(종속) 변수가 있고 부모가 "All"을 사용하면 같은 패턴을 적용해요. 예를 들어 region이 hostname에 연결될 때:

hostname 변수 쿼리:

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

패널 쿼리:

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 절을 조건부로 생략하는 기본 지원이 없어요. 조건부 필터링을 위해 다음 패턴 중 하나를 사용해요.

패턴: 항상-참 조건

변수를 무시해야 할 때 참으로 평가되는 조건을 사용해요.

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

패턴: 선택적 필터의 CASE 표현식

더 복잡한 시나리오에는 CASE 표현식을 사용해요.

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에서 템플릿 변수를 사용할 때 다음 동작을 알아두세요.

multi-value 변수의 자동 따옴표

Grafana v11.3부터 IN 연산자와 함께 사용되는 multi-value 변수는 자동으로 따옴표 처리돼요. 이전에 수동 따옴표로 WHERE col IN ('${var}')을 작성했다면 수동 따옴표를 제거하고 WHERE col IN ($var)를 사용하세요.

문자열 리터럴 내부의 주석

Grafana SQL 쿼리 파서는 매크로 보간 전에 SQL 주석(-- 및 /* */)을 제거해요. 어떤 경우에는 따옴표로 묶인 문자열 리터럴 내부의 --가 주석으로 잘못 해석될 수 있어요. --를 포함하는 문자열이 있는 쿼리라면 쿼리 실행 후 Generated SQL을 클릭해 쿼리가 올바르게 확장되는지 확인하세요.

알림 쿼리의 변수

알림 쿼리에서 템플릿 변수는 지원되지 않아요. Grafana는 대시보드 컨텍스트 없이 백엔드에서 알림 규칙을 평가해요. 대시보드 쿼리가 변수를 사용한다면 하드코딩된 값으로 별도의 알림 쿼리를 만들어요. 자세한 내용은 Microsoft SQL Server 알림 참고.

더 알아보기 (Learn more)

Add and manage variables - 변수 추가·관리
MSSQL query editor - 쿼리 편집기
Variable syntax - 변수 문법
MSSQL alerting - 알림
Microsoft SQL Server template variables - 원문 문서

Microsoft SQL Server 템플릿 변수