MySQL 쿼리 편집기
MySQL 쿼리 편집기
그라파나의 쿼리 편집기는 데이터 소스마다 고유합니다. MySQL 쿼리 편집기는 Explore 페이지에 있으며, 대시보드 패널에서도 접근할 수 있어요 — 패널 오른쪽 위의 말줄임표를 클릭하고 Edit을 선택하면 됩니다. Builder(시각적)와 Code(고급 SQL) 두 가지 모드를 제공합니다.
본문
참고: 데이터 소스 구성 페이지에 기본 데이터베이스가 구성되어 있거나 프로비저닝 구성 파일로 설정되어 있으면, 사용자는 그 사전 구성된 데이터베이스만 쿼리하도록 제한됩니다.
MySQL 쿼리 편집기 구성 요소
MySQL 쿼리 편집기는 Builder와 Code 두 가지 모드가 있습니다. Builder 모드는 시각적 인터페이스로 쿼리를 만들고, Code 모드는 복잡한 SQL 작성을 지원하는 고급 쿼리입니다.
참고: 테이블이나 데이터베이스 이름에 예약어나 금지 문자(prohibited character)가 포함되면 편집기가 이름 주위에 따옴표를 붙입니다. 예를 들어
table-name이라는 이름은 백틱으로 감싸져`table-name`이 됩니다.
Builder 모드
MySQL 쿼리를 만드는 데 도움을 주는 구성 요소:
- Format – 드롭다운에서 MySQL 쿼리의 응답 형식을 선택합니다. 기본값은 Table입니다. Time series 형식 옵션을 쓰면 열 중 하나가
time이어야 합니다. - Dataset – 드롭다운에서 쿼리할 데이터베이스를 선택합니다. Table – 드롭다운에서 테이블을 선택합니다(선택한 데이터베이스에 해당). Data operations – 드롭다운에서 집계를 선택합니다. + 기호로 여러 데이터 연산을 추가하고 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 함수, 그라파나 템플릿 변수, 그라파나 매크로의 자동 완성을 지원합니다. 테이블이 지정되기 전에는 열 자동 완성이 되지 않습니다.
Table 또는 Time series 형식을 선택합니다. 오른쪽 아래의 **{}**를 클릭해 쿼리를 포맷하고, 아래쪽 캐럿을 클릭해 Code 모드 편집기를 펼칩니다. CTRL/CMD + Return은 쿼리 실행 단축키입니다.
경고: Code 모드에서 쿼리를 변경한 것은 Builder 모드로 전송되지 않으며 버려집니다. 그라파나는 변경 사항을 저장하려면 코드를 클립보드에 복사하라고 안내합니다.
매크로(Macros)
쿼리에 매크로를 추가하면 문법을 단순화하고 날짜 범위 필터 같은 동적 요소를 활성화할 수 있습니다.
| 매크로 예시 | 설명 |
|---|---|
$__time(dateColumn) |
UNIX 타임스탬프로 변환하는 표현식으로 값을 바꾸고 열 이름을 time_sec으로 바꿉니다. Time Series 형식에 필요한 time 열을 인식하게도 합니다. 예: UNIX_TIMESTAMP(dateColumn) AS time_sec. |
$__timeEpoch(dateColumn) |
UNIX Epoch 타임스탬프로 변환하는 표현식으로 값을 바꾸고 열 이름을 time_sec으로 바꿉니다. 예: UNIX_TIMESTAMP(dateColumn) AS time_sec. |
$__timeFilter(dateColumn) |
지정한 열 이름으로 시간 범위 필터를 적용하고 그 범위에 해당하는 데이터만 가져옵니다. 예: dateColumn BETWEEN FROM_UNIXTIME(1494410783) AND FROM_UNIXTIME(1494410983). |
$__timeFrom() |
현재 활성 시간 선택의 시작으로 값을 바꿉니다. 예: FROM_UNIXTIME(1494410783). |
$__timeTo() |
현재 활성 시간 선택의 끝으로 값을 바꿉니다. 예: FROM_UNIXTIME(1494410983). |
$__timeGroup(dateColumn,'5m') |
GROUP BY 절에 적합한 표현식으로 값을 바꾸고 고정 간격의 버킷 타임스탬프를 만듭니다. 예: cast(cast(UNIX_TIMESTAMP(dateColumn)/(300) as signed)*300 as signed). |
$__timeGroup(dateColumn,'5m', 0) |
$__timeGroup(dateColumn,'5m')과 같지만, 누락된 계열 지점을 그라파나가 0으로 채우는 fill 매개변수를 포함합니다. time series 쿼리에만 적용됩니다. |
$__timeGroup(dateColumn,'5m', NULL) |
$__timeGroup(dateColumn,'5m', 0)과 같지만 누락 지점에 NULL을 사용합니다. time series 쿼리에만 적용됩니다. |
$__timeGroup(dateColumn,'5m', previous) |
$__timeGroup(dateColumn,'5m', 0)과 같지만 이전 계열 값을 fill 값으로 사용합니다. 이전 값이 없으면 NULL을 사용합니다. time series 쿼리에만 적용됩니다. |
$__timeGroupAlias(dateColumn,'5m') |
$__timeGroup과 동일하지만 열 별칭이 추가된 값으로 바꿉니다. |
$__unixEpochFilter(dateColumn) |
UNIX 타임스탬프로 표현된 시간과 함께 지정한 열 이름으로 시간 범위 필터로 값을 바꿉니다. 예: dateColumn > 1494410783 AND dateColumn < 1494497183. |
$__unixEpochNanoFilter(dateColumn) |
나노초 타임스탬프로 표현된 시간과 함께 지정한 열 이름으로 시간 범위 필터로 값을 바꿉니다. |
$__unixEpochNanoFrom() |
현재 활성 시간 선택의 시작을 나노초 타임스탬프로 바꿉니다. |
$__unixEpochNanoTo() |
현재 활성 시간 선택의 끝을 나노초 타임스탬프로 바꿉니다. |
$__unixEpochGroup(dateColumn,'5m', [fillmode]) |
$__timeGroup과 같지만 Unix 타임스탬프로 저장된 시간용입니다. fillMode는 time series 쿼리에서만 작동합니다. |
$__unixEpochGroupAlias(dateColumn,'5m', [fillmode]) |
$__timeGroup과 같지만 열 별칭도 추가합니다. fillMode는 time series 쿼리에서만 작동합니다. |
참고: Grafana 13.0부터
$__timeGroup과$__unixEpochGroup의 fill 리샘플링에는 쿼리가 행을 반환하지 않거나 시간 범위가 데이터 경계 밖일 때 잘못된 데이터 지점을 방지하는 추가 안전장치가 포함됩니다.
Table SQL 쿼리
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)
Time series 쿼리
Format 옵션을 Time series로 설정해 시계열 쿼리를 만들고 실행할 수 있습니다.
참고: 시계열 쿼리를 실행하려면 SQL datetime 값 또는 UNIX epoch 초를 나타내는 숫자 자료형을 반환하는
time열이 있어야 합니다. 또한 쿼리 결과가 time 열 기준으로 정렬되어야 패널에 제대로 표시됩니다.
이 섹션의 예시는 다음 테이블의 데이터를 참조합니다.
+---------------------+--------------+---------------------+----------+
| time_date_time | value_double | CreatedAt | hostname |
+---------------------+--------------+---------------------+----------+
| 2025-01-02 03:05:00 | 3.0 | 2025-01-02 03:05:00 | 10.0.1.1 |
| 2025-01-02 03:06:00 | 4.0 | 2025-01-02 03:06:00 | 10.0.1.2 |
| 2025-01-02 03:10:00 | 6.0 | 2025-01-02 03:10:00 | 10.0.1.1 |
| 2025-01-02 03:11:00 | 7.0 | 2025-01-02 03:11:00 | 10.0.1.2 |
| 2025-01-02 03:20:00 | 5.0 | 2025-01-02 03:20:00 | 10.0.1.2 |
+---------------------+--------------+---------------------+----------+
참고: 하위 호환성을 위해,
metric이라는 문자열 열을 포함해 세 개의 열을 반환하는 쿼리에는 앞선 규칙의 예외가 적용됩니다. metric 열을 필드 라벨로 변환하는 대신 필드 이름으로 사용하고, 계열 이름은 metric 열의 값으로 설정합니다.
$__time(dateColumn) 매크로 예시:
SELECT
$__time(time_date_time),
value_double
FROM my_data
ORDER BY time_date_time
이 예시의 결과에는 고정 타임스탬프와 연결된 데이터를 나타내는 Time과 value_double 두 열이 포함됩니다. 이 쿼리는 시간 범위 필터를 적용하지 않고 테이블의 모든 행을 반환합니다.
$__timeFilter(dateColumn) 매크로 예시:
SELECT
$__time(time_date_time),
value_double
FROM my_data
WHERE $__timeFilter(time_date_time)
ORDER BY time_date_time
이 예시는 이전과 같은 결과를 반환하지만, 그라파나 시간 선택기로 데이터를 필터링하는 지원을 추가합니다.
$__timeGroup(dateColumn,'5m') 매크로 예시:
SELECT
$__timeGroup(time_date_time, '5m') AS time,
sum(value_double) AS sum_value
FROM my_data
WHERE $__timeFilter(time_date_time)
GROUP BY time
ORDER BY time
이 예시의 결과에서 데이터는 고정 간격(여기선 5분)의 타임스탬프 버킷으로 그룹화되고 집계됩니다. 기본 계열 이름 포맷을 커스터마이즈하려면 표준 옵션 정의 문서를 참조하세요.
$__timeGroupAlias(dateColumn,'5m') 매크로 예시:
SELECT
$__timeGroupAlias(time_date_time,'5m'),
min(value_double),
'min' as metric
FROM my_data
WHERE $__timeFilter(time_date_time)
GROUP BY time
ORDER BY time
이 결과는 $__timeGroup(dateColumn,'5m') 매크로의 결과와 비슷하지만 time 열에 내장 별칭을 사용합니다.
$__timeGroupAlias 매크로로 null 값을 0으로 변환하는 예시:
SELECT
$__timeGroupAlias(createdAt,'5m',0),
sum(value_double) as value,
hostname
FROM my_data
WHERE
$__timeFilter(createdAt)
GROUP BY time, hostname
ORDER BY time
이 예시의 결과에서 버킷 타임스탬프 내의 null 값은 0으로 치환되고 기본적으로 Time 열 별칭도 추가됩니다. ${__field.labels.hostname} 값을 표시하려면 표준 옵션 정의 문서를 참조하세요.
여러 열 $__timeGroupAlias(dateColumn,'5m') 매크로 예시:
SELECT
$__timeGroupAlias(time_date_time,'5m'),
min(value_double) as min_value,
max(value_double) as max_value
FROM my_data
WHERE $__timeFilter(time_date_time)
GROUP BY time
ORDER BY time
이 쿼리는 정의된 범위 내 최소값과 최대값을 나타내는 여러 열을 반환합니다.
템플릿 변수
메트릭 쿼리에 서버, 애플리케이션, 센서 이름 같은 값을 하드코딩하는 대신 변수를 사용할 수 있습니다. 변수는 대시보드 상단에 드롭다운 선택 상자로 나타나 대시보드에 표시되는 데이터를 쉽게 바꿀 수 있게 해줍니다.
주석(Annotations)
주석을 사용하면 그래프에 이벤트 정보를 오버레이해 이벤트와 메트릭을 연관 지을 수 있습니다. 대시보드에 주석으로 표시할 이벤트 데이터를 반환하는 SQL 쿼리를 작성할 수 있습니다.
경고(Alerting)
시계열 쿼리를 사용해 Grafana-managed 경고 규칙을 만들 수 있습니다. Table 형식 쿼리는 경고 규칙 조건에서 지원되지 않습니다.