PostgreSQL 쿼리 편집기

PostgreSQL 쿼리 편집기는 데이터 소스에 대해 쿼리를 작성하고 실행하게 해줍니다. 일반적인 쿼리 편집기와 데이터 변환 개념은 "쿼리와 데이터 변환" 문서를 참조하세요. Explore 페이지나 대시보드 패널에서 편집기를 열 수 있어요 — 패널 오른쪽 위의 점 세 개(말줄임표)를 클릭하고 Edit을 선택하면 됩니다.

출처: PostgreSQL query editor

본문

참고: 데이터 소스 설정에 기본 데이터베이스가 구성되어 있어야 합니다. 설정되지 않았거나 제거되면 데이터베이스가 다시 구성될 때까지 데이터 소스는 쿼리를 실행하지 않습니다.

PostgreSQL 쿼리 편집기 구성 요소

PostgreSQL 쿼리 편집기에는 Builder와 Code 두 가지 모드가 있습니다. Builder 모드는 시각적 인터페이스로 쿼리를 만들고, Code 모드는 복잡한 SQL 쿼리 작성이 가능한 고급 쿼리를 지원합니다.

Builder 모드

PostgreSQL 쿼리를 만드는 데 도움을 주는 구성 요소:

Format – 드롭다운에서 쿼리 결과 형식을 선택합니다. 기본값은 Table입니다. Time series 형식 옵션을 쓰면 열 중 하나가 time이어야 합니다.
Table – 드롭다운에서 테이블을 선택합니다. 테이블은 선택한 데이터베이스에 해당합니다.
Data operations – 선택. 드롭다운에서 집계(aggregation)를 선택합니다. + 기호를 클릭해 여러 데이터 연산을 추가할 수 있고, 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 쿼리 미리보기 토글입니다. 기본적으로 켜져 있습니다.

Code 모드

고급 쿼리를 만들려면 편집기 창 오른쪽 위의 Code를 클릭해 Code 모드로 전환합니다. Code 모드는 테이블, 열, SQL 키워드, 표준 SQL 함수, 그라파나 템플릿 변수, 그라파나 매크로의 자동 완성을 지원합니다. 테이블이 지정되기 전에는 열 자동 완성이 되지 않습니다.

참고: 테이블이나 열 이름이 예약어이거나 대소문자가 섞였거나 특수 문자가 포함되면 SQL에서 큰따옴표를 사용하세요. 예: "user" 또는 "Created At".

Table 또는 Time series 형식을 선택합니다. 오른쪽 아래의 **{}**를 클릭해 쿼리를 포맷합니다. 아래쪽 캐럿(^)을 클릭해 Code 모드 편집기를 펼칩니다. CTRL/CMD + Return은 쿼리를 실행하는 단축키입니다.

경고: Code 모드에서 쿼리를 변경한 것은 Builder 모드로 전송되지 않으며 버려집니다. 변경 사항을 저장하려면 코드를 클립보드에 복사하라는 안내가 표시됩니다.

매크로(Macros)

쿼리에 매크로를 추가하면 문법을 단순화하고 날짜 범위 필터 같은 동적 요소를 활성화할 수 있습니다. 그라파나는 쿼리를 실행하기 전에 매크로를 네이티브 PostgreSQL SQL로 확장합니다. TimescaleDB 확장이 활성화되면 $__timeGroup과 $__timeGroupAlias는 더 효율적인 그룹화를 위해 time_bucket()을 사용합니다.

시계열 매크로

매크로 예시	설명
`$__time(dateColumn)`	열 이름을 `time`으로 바꿉니다. 예: `dateColumn AS "time"`. 네이티브 날짜/시간 열에 사용합니다.
`$__timeEpoch(dateColumn)`	UNIX epoch(초)로 변환하고 열 이름을 `time`으로 바꿉니다. 예: `extract(epoch from dateColumn) as "time"`. 열 인수가 필요합니다.
`$__timeFilter(dateColumn)`	지정한 열 이름으로 시간 범위 필터로 값을 바꿉니다. 예: `dateColumn BETWEEN '2020-07-13T20:19:09.254Z' AND '2020-07-13T21:19:09.254Z'`.
`$__timeFrom()`	현재 활성 시간 선택의 시작(RFC3339Nano)으로 값을 바꿉니다.
`$__timeTo()`	현재 활성 시간 선택의 끝(RFC3339Nano)으로 값을 바꿉니다.
`$__timeGroup(dateColumn,'5m')`	GROUP BY 절에 적합한 표현식으로 값을 바꿉니다. 예: `floor(extract(epoch from dateColumn)/300)*300`. TimescaleDB 사용 시: `time_bucket('300s', dateColumn)`.
`$__timeGroup(dateColumn,'5m', 0)`	`$__timeGroup(dateColumn,'5m')`과 같지만, 누락된 계열 지점을 그라파나가 0으로 채우는 fill 매개변수를 포함합니다. fill은 time series 쿼리에만 적용됩니다.
`$__timeGroup(dateColumn,'5m', NULL)`	`$__timeGroup(dateColumn,'5m', 0)`과 같지만 누락 지점에 NULL을 사용합니다. fill은 time series 쿼리에만 적용됩니다.
`$__timeGroup(dateColumn,'5m', previous)`	`$__timeGroup(dateColumn,'5m', 0)`과 같지만 이전 계열 값을 채움 값으로 사용합니다. 이전 값이 없으면 NULL을 사용합니다. fill은 time series 쿼리에만 적용됩니다.
`$__timeGroupAlias(dateColumn,'5m')`	`$__timeGroup`과 같지만 `AS "time"` 열 별칭이 추가됩니다. TimescaleDB에서는 `time_bucket()`을 사용합니다.

UNIX epoch 매크로

매크로 예시	설명
`$__unixEpochFilter(dateColumn)`	UNIX epoch(초)를 저장하는 열의 시간 범위 필터로 값을 바꿉니다. 예: `dateColumn >= 1494410783 AND dateColumn <= 1494497183`.
`$__unixEpochFrom()`	현재 활성 시간 선택의 시작을 UNIX 타임스탬프(초)로 바꿉니다.
`$__unixEpochTo()`	현재 활성 시간 선택의 끝을 UNIX 타임스탬프(초)로 바꿉니다.
`$__unixEpochNanoFilter(dateColumn)`	나노초 단위의 UNIX epoch를 저장하는 열의 시간 범위 필터로 값을 바꿉니다.
`$__unixEpochNanoFrom()`	현재 활성 시간 선택의 시작을 나노초 타임스탬프로 바꿉니다.
`$__unixEpochNanoTo()`	현재 활성 시간 선택의 끝을 나노초 타임스탬프로 바꿉니다.
`$__unixEpochGroup(dateColumn,'5m', [fillmode])`	`$__timeGroup`과 같지만 UNIX epoch(초)를 저장하는 열용입니다. 예: `floor((dateColumn)/300)*300`. fillMode는 time series 쿼리에만 적용됩니다.
`$__unixEpochGroupAlias(dateColumn,'5m', [fillmode])`	`$__unixEpochGroup`과 같지만 `AS "time"` 별칭이 추가됩니다. fillMode는 time series 쿼리에만 적용됩니다.

간격 변수

나열된 매크로 외에도 다음 그라파나 간격 변수가 쿼리 실행 전에 치환됩니다.

변수	설명
`$__interval`	시간 범위와 패널 너비를 기반으로 계산된 간격(예: `5m`)으로 치환됩니다. `$__timeGroup`이나 커스텀 표현식에서 직접 사용합니다.
`$__interval_ms`	`$__interval`과 같지만 밀리초 단위(예: `300000`)입니다.

이 변수들의 하한은 데이터 소스 구성의 Min time interval 옵션이나 패널의 쿼리 옵션에서 설정할 수 있습니다.

매크로 동작

매크로 사용 시 다음 동작을 기억하세요.

주석 제거 – 그라파나는 매크로를 확장하기 전에 SQL 주석(-- 라인 주석과 /* */ 블록 주석)을 제거합니다. 주석 안에 있는 매크로는 확장되지 않습니다.
TimescaleDB 모드 – 데이터 소스 구성에서 TimescaleDB 토글이 켜져 있으면 $__timeGroup과 $__timeGroupAlias는 floor(extract(epoch ...)) 대신 PostgreSQL time_bucket() 함수를 사용합니다.
후행 쉼표 패턴 – $__timeGroup(...) 호출 바로 뒤에 쉼표(,)가 오면 자동으로 $__timeGroupAlias(...)로 처리되어 AS "time" 별칭이 추가됩니다. 레거시 편의 기능이며, 명확성을 위해 $__timeGroupAlias를 명시적으로 사용하세요.
확장된 SQL 검사 – 매크로 확장 후 최종 SQL을 보려면 패널에서 Query inspector를 열고 데이터베이스로 보낸 쿼리를 확인하세요.

Table 쿼리

Format 옵션이 Table로 설정되어 있으면 사실상 모든 종류의 SQL 쿼리를 실행할 수 있습니다. Table 패널은 쿼리 결과의 열과 행을 자동으로 표시합니다.

Table 패널 열 이름은 SQL 키워드 AS 문법으로 변경하거나 커스터마이즈할 수 있습니다.

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 변수로 필터링하려면:

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 템플릿 변수 문서를 참조하세요.

시간 범위 열이 있는 Table 쿼리

Table 형식 쿼리는 time 열 외에 timeend 열을 지원합니다. 둘 다 있으면 그라파나는 그 행을 단일 지점이 아닌 시간 범위로 취급합니다. 유지보수 창이나 배포처럼 지속 시간이 있는 이벤트를 표시할 때 유용합니다.

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

Time series 쿼리

Format 옵션을 Time series로 설정해 시계열 쿼리를 만들고 실행할 수 있습니다.

참고: 시계열 쿼리를 실행하려면 SQL datetime 값 또는 UNIX epoch 초를 나타내는 숫자 자료형을 반환하는 time 열이 있어야 합니다. 또한 패널에서 올바르게 시각화하려면 쿼리 결과가 time 열 기준으로 정렬되어야 합니다.

이 섹션의 예시는 다음 테이블의 데이터를 참조합니다.

+---------------------+--------------+---------------------+----------+
| 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 |
+---------------------+--------------+---------------------+----------+

시계열 쿼리 결과는 와이드 데이터 프레임 형식으로 반환됩니다. 데이터 프레임 쿼리 결과에서 time이나 문자열형 열을 제외한 모든 열은 값 필드로 변환되고, 문자열 열은 필드 라벨이 됩니다.

메트릭 열 감지

PostgreSQL 플러그인은 문자열형 열(text, varchar, char, bpchar)을 라벨 열로 식별해 결과를 여러 계열로 나눕니다. 숫자 및 시간 열은 값 필드가 됩니다.

참고: 하위 호환성을 위해, 세 개의 열을 반환하고 그중 하나가 metric이라는 이름의 문자열 열인 쿼리에는 예외가 적용됩니다. metric 열을 필드 라벨로 변환하는 대신 필드 이름으로 사용하고, 계열 이름은 그 값으로 설정합니다.

누락된 시계열 지점 채우기

$__timeGroup이나 $__unixEpochGroup을 fill 매개변수(세 번째 인수)와 함께 사용하면 그라파나가 시계열 데이터의 빈틈을 채웁니다. 데이터 간격이 불규칙하거나 데이터 지점이 없을 때 유용합니다. fill은 time series 형식 쿼리에서만 작동합니다.

사용 가능한 fill 모드:

Fill 모드	동작
`0` (또는 아무 숫자)	누락 지점을 지정한 숫자 값으로 채웁니다.
`NULL`	누락 지점을 `NULL`로 채워 라인 차트에 빈틈을 만듭니다.
`previous`	누락 지점에 마지막으로 알려진 값을 사용합니다. 이전 값이 없으면 `NULL`을 사용합니다.

예를 들어 $__timeGroupAlias("CreatedAt",'5m', 0)은 데이터를 5분 간격으로 그룹화하고 빈틈을 0으로 채웁니다.

참고: Grafana 13.0부터 $__timeGroup과 $__unixEpochGroup의 fill 모드에는 쿼리가 행을 반환하지 않거나 시간 범위가 데이터 경계 밖일 때 잘못된 데이터 지점을 방지하는 추가 안전장치가 포함됩니다.

행 제한

그라파나는 과도한 메모리 사용을 막기 위해 쿼리 결과에 서버 측 행 제한을 적용합니다. 쿼리가 제한보다 많은 행을 반환하면 결과가 잘립니다. 반환 행 수를 줄이려면 대시보드 시간 범위를 좁히거나, $__timeGroup 간격을 늘리거나, 쿼리에 LIMIT 절을 추가하세요.

metric 열 예시:

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

데이터 프레임 결과:

+---------------------+-----------------+
| 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/value 지점을 반환하려면 $__time으로 날짜/시간 열을 time으로 별칭합니다.

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

$__timeGroupAlias 매크로에 fill 매개변수를 사용해 null 값을 0으로 변환하는 예시:

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

아래 예시의 데이터 프레임 결과를 기준으로, time series 패널은 value 10.0.1.1과 value 10.0.1.2라는 두 계열을 생성합니다. 계열 이름을 10.0.1.1과 10.0.1.2로 표시하려면 표준 옵션 정의의 표시 값 ${__field.labels.hostname}를 사용하세요.

데이터 프레임 결과:

+---------------------+---------------------------+---------------------------+
| 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                         |
+---------------------+---------------------------+---------------------------+

여러 열 예시:

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

데이터 프레임 결과:

+---------------------+-----------------+-----------------+
| 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 별칭을 만들고 WHERE 절에서 $__unixEpochFilter를 사용합니다.

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

epoch 열이 있는 그룹화 시계열에는 $__unixEpochGroupAlias와 $__unixEpochFilter를 사용합니다. 자세한 내용은 매크로 표를 참조하세요.

EXPLAIN 쿼리

Code 모드에서 EXPLAIN 및 EXPLAIN ANALYZE 쿼리를 실행해 쿼리 실행 계획을 검사할 수 있습니다. 결과는 테이블로 반환되며, 그라파나에서 직접 느린 쿼리를 진단할 때 유용합니다.

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

그라파나 매크로는 쿼리가 실행되기 전에 확장되므로 EXPLAIN 쿼리에서 $__timeFilter 같은 매크로를 사용해 대시보드 시간 범위의 실제 실행 계획을 볼 수 있습니다. Format을 Table로 설정해 계획 출력을 표시하세요.

다음 단계

템플릿 변수를 사용해 동적이고 재사용 가능한 대시보드를 만듭니다.
PostgreSQL에서 주석을 추가해 패널에 이벤트를 오버레이합니다.
메트릭이 임계값을 넘을 때 알림을 받도록 경고를 설정합니다(time series 형식 전용).
쿼리 문제가 발생하면 트러블슈팅합니다.

PostgreSQL 쿼리 편집기

PostgreSQL 쿼리 편집기

본문

PostgreSQL 쿼리 편집기 구성 요소

Builder 모드

Code 모드

매크로(Macros)

시계열 매크로

UNIX epoch 매크로

간격 변수

매크로 동작

Table 쿼리

시간 범위 열이 있는 Table 쿼리

Time series 쿼리

메트릭 열 감지

누락된 시계열 지점 채우기

행 제한

EXPLAIN 쿼리

다음 단계

더 알아보기