PostgreSQL 템플릿 변수

PostgreSQL 템플릿 변수 (PostgreSQL template variables)

메트릭 쿼리에서 서버·애플리케이션·센서 이름을 하드코딩하지 않고 변수를 사용할 수 있어요. Grafana는 변수를 대시보드 상단의 드롭다운에 표시해 데이터를 쉽게 바꾸게 해 주는데, 이를 템플릿 변수라고 해요. PostgreSQL 데이터 소스는 전용 변수 쿼리 편집기와 다중 속성(multi-property) 변수 지원이 특징이에요.

출처: 문서

본문

템플릿과 템플릿 변수 소개는 Templating과 변수 추가·관리 문서를 참고하세요.

쿼리 변수

쿼리 변수는 쿼리로 데이터 소스에서 값을 동적으로 가져와요. PostgreSQL 데이터 소스에는 전체 SQL 편집기(자동완성·문법 강조 지원 Code 모드)와 Value Field/Text Field 드롭다운이 있는 전용 변수 쿼리 편집기가 있어요. 쿼리를 작성·실행하면 편집기가 반환 컬럼을 자동으로 감지해 필드 드롭다운을 채워, 어느 컬럼이 변수 값이고 어느 컬럼이 표시 라벨인지 매핑할 수 있게 해줍니다.

쿼리 변수 만들기:

대시보드에서 Edit 클릭 → Add new element → Variable 클릭
변수 유형으로 Query 선택, Name 입력(예: host), Display 위치 선택
Open variable editor → Query Variable 대화상자에서 PostgreSQL 데이터 소스 선택
SQL 쿼리 작성($__timeFilter 같은 매크로 지원)
(선택) Value Field/Text Field로 변수 값·표시 라벨 매핑

hostname 컬럼의 모든 값을 반환하는 예:

SELECT hostname FROM host

여러 컬럼 반환 시 Grafana가 그 값들을 자동으로 목록으로 생성해요.

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

시간 범위 의존 매크로($__timeFilter(column))를 사용하려면 refresh 모드를 On Time Range Change로 설정하세요.

SELECT event_name FROM event_log WHERE $__timeFilter(time_column)

키/값 변수

드롭다운에 라벨(hostname)을, 패널 쿼리에는 다른 값(ID)을 쓰려면 Value field/Text field로 매핑하세요. SQL에 __value/__text가 필요 없어요(레이거시로는 SELECT hostname AS __text, id AS __value FROM host도 가능). 텍스트 컬럼 값은 고유해야 해요.

SELECT hostname, id FROM host

중첩 변수

한 변수가 다른 변수에 의존하게 할 수 있어요. region이 다중 값이면 = 대신 IN 연산자를 쓰세요.

SELECT hostname FROM host WHERE region IN($region)

참고: Include All option을 켜고 Display를 Hidden으로 설정한 다중 값 PostgreSQL 쿼리 변수는 기본값이 All이 아니라 첫 번째 반환 값이 됩니다. 숨겨진 변수는 사용자가 바꿀 UI가 없기 때문이에요. All로 기본 설정하려면 변수를 임시로 표시하고 All을 선택·저장한 뒤 다시 숨기세요.

__searchFilter로 결과 필터링

드롭다운 입력에 따라 결과를 필터링하려면 __searchFilter를 따옴표로 감싸 사용하세요(기본값 %). 큰 테이블에서는 LIMIT와 함께 쓰면 반응성이 좋아져요.

SELECT hostname FROM host WHERE hostname LIKE '$__searchFilter'

SELECT DISTINCT hostname
FROM host
WHERE hostname LIKE '$__searchFilter'
ORDER BY hostname
LIMIT 100

Regex 변수

Regex 유형 변수로 다른 변수의 값을 필터링/변환할 수 있어요. 예: server 변수가 web-prod-01, web-staging-01 등을 반환할 때 정규식 /^web-(.+)-\\d+$/로 prod, staging 추출. Regex 필드를 /prod/로 설정하면 프로덕션 서버만 남길 수도 있어요.

다중 속성 변수

PostgreSQL 데이터 소스는 multi-property 변수(같은 논리 개념이 컨텍스트별로 다른 식별자를 가질 때, 예: 한 시스템의 dev와 다른 시스템의 development)를 지원해요. 여러 변수를 동기화하는 대신 모든 값을 한 변수에 매핑하고 각 패널/쿼리에서 필요한 속성을 참조할 수 있어요.

Type: Custom – Custom options > JSON에 매핑을 담은 JSON 배열을 붙여넣기. 각 객체는 원하는 만큼 속성을 가질 수 있고, 드롭다운 라벨·값에는 text/value 사용.
Type: Query – 여러 컬럼을 반환하는 SQL 쿼리 작성. Value field/Text field에 값·라벨 컬럼 지정. 참조하려는 속성마다 컬럼을 하나씩 추가하고, 컬럼 이름이 속성 이름이 됩니다. 패널/쿼리에서 ${varName.columnName}으로 참조.

예제(Type: Query): 클라우드별로 식별자가 다른 환경 목록을 반환하는 env 변수. Text field를 name, Value field를 id로 설정.

SELECT
  name,
  id,
  aws_identifier AS env_aws,
  azure_identifier AS env_azure
FROM environments

패널 쿼리에서 AWS 쪽은 $env.env_aws, Azure 쪽은 $env.env_azure를 사용할 수 있어요.

쿼리에서 변수 사용하기

Grafana는 템플릿 변수가 multi-value일 때만 자동으로 따옴표를 붙여요. 다중 값 변수는 = 대신 IN 연산자를 쓰세요. 두 가지 문법 지원: $<varname>과 [[varname]].

SELECT
  atimestamp AS time,
  aint AS value
FROM table
WHERE $__timeFilter(atimestamp) AND hostname IN($hostname)
ORDER BY atimestamp ASC

다중 값 변수와 IN 절

Multi-value가 활성화되면 Grafana가 각 선택 값에 자동으로 따옴표를 추가해요. web01,web02 선택 시 $hostname은 'web01','web02'로 확장됩니다. IN 연산자로 매칭하세요. 단일 값 선택 시에도 IN('web01')은 = 'web01'과 동일하게 동작해요.

SELECT
  $__timeGroupAlias("created_at", '5m'),
  count(*) AS requests
FROM access_log
WHERE $__timeFilter("created_at")
  AND hostname IN($hostname)
GROUP BY time
ORDER BY time

숫자 컬럼 다중 값 변수

ID 같은 숫자 컬럼에는 csv 포맷 옵션으로 따옴표를 끄세요.

SELECT name FROM host WHERE id IN(${host_id:csv})

1,2,3 선택 시 IN(1,2,3)으로 확장됩니다(IN('1','2','3') 대신).

다중 값 변수의 따옴표 비활성화

기본적으로 다중 값 변수는 따옴표가 붙은 콤마 구분 문자열('server01','server02')로 포맷돼요. csv 포맷 옵션으로 끄세요.

${servers:csv}

추가 정보는 고급 변수 포맷 옵션을 참고하세요.

PostgreSQL 템플릿 변수