`으로 확장되며, 그렇지 않으면 `1=1`로 확장됩니다. |
변수 값은 `$name` 또는 `${name}`으로 직접 보간할 수도 있으며, 선택적으로 포맷을 지정할 수 있습니다. `${name:sqlstring}`(기본값), `${name:csv}`, `${name:regex}`를 사용할 수 있습니다. 기본 포맷에서 직접 참조하면 아무 값도 선택되지 않은 경우 `NULL`이 렌더링되므로, 프레디케이트가 필요한 곳에서는 위 매크로를 사용하는 것이 좋습니다.
## 쿼리 결과가 차트에 표시되는 방법
ClickStack는 컬럼 타입에 따라 결과 컬럼을 차트 요소에 자동으로 매핑합니다. 매핑 규칙은 차트 유형별로 다릅니다.
### Line 및 Stacked Bar 차트
| 역할 | 컬럼 유형 | 설명 |
| --------- | ---------------------------- | ------------------------------------------- |
| **타임스탬프** | 첫 번째 `Date` 또는 `DateTime` 컬럼 | x축으로 사용됩니다. |
| **시리즈 값** | 모든 숫자형 컬럼 | 각 숫자형 컬럼은 각각 별도의 시리즈로 그려집니다. 일반적으로 집계 값입니다. |
| **그룹 이름** | String, 맵 또는 배열 컬럼 | 선택 사항입니다. 그룹 값이 서로 다른 행은 각각 별도의 시리즈로 그려집니다. |
### 파이 차트
| 역할 | 컬럼 유형 | 설명 |
| ---------- | ------------------ | ------------------------------- |
| **조각 값** | 첫 번째 숫자형 컬럼 | 각 조각의 크기를 결정합니다. |
| **조각 레이블** | String, 맵 또는 배열 컬럼 | 선택 사항입니다. 고유한 각 값이 조각 레이블이 됩니다. |
### 숫자 차트
| 역할 | 컬럼 유형 | 설명 |
| ------ | ---------- | ---------------------------- |
| **숫자** | 첫 번째 숫자 컬럼 | 첫 번째 숫자 컬럼의 첫 번째 행 값이 표시됩니다. |
### 테이블 차트
모든 결과 컬럼이 테이블의 컬럼으로 직접 표시됩니다.
## 예시
**필수 system table 접근 권한**
[play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com)에서 다음 예시를 실행하려면 `otel_v2.otel_logs` 또는 `otel_v2.otel_traces`를 지정해야 합니다.
### 라인 차트 — 서비스별 시간대별 로그 수
이 쿼리는 대시보드 세분화 수준에 맞춰 시간 인터벌별로 로그 이벤트 수를 서비스별로 집계합니다.
```sql theme={null}
SELECT
toStartOfInterval(TimestampTime, INTERVAL {intervalSeconds:Int64} second) AS ts,
ServiceName,
count() AS count
FROM otel_logs
WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
AND $__filters
GROUP BY ServiceName, ts
ORDER BY ts ASC
```
* `ts` (DateTime)는 x축 타임스탬프로 사용됩니다.
* `count` (numeric)는 시리즈 값으로 표시됩니다.
* `ServiceName` (string)은 서비스마다 별도의 선을 생성합니다.
### 라인 차트 — 매크로 사용
간결하게 표현하기 위해 매크로를 사용해 동일한 쿼리를 작성하면 다음과 같습니다:
```sql theme={null}
SELECT
$__timeInterval(TimestampTime) AS ts,
ServiceName,
count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
AND $__filters
GROUP BY ServiceName, ts
ORDER BY ts ASC
```
### 라인 차트 — 대시보드 변수 사용
`ServiceName`에 대한 `service` 변수와 `SeverityText`에 대한 `severity` 변수가 있는 대시보드에서 이 쿼리는 차트를 현재 선택된 서비스로 제한하고 선택된 심각도는 제외합니다. 두 매크로는 변수에서 아무것도 선택되지 않은 경우 `1=1`로 확장되므로, Viewer가 값을 선택하기 전까지 차트는 필터링 없이 표시됩니다.
```sql theme={null}
SELECT
$__timeInterval(TimestampTime) AS ts,
count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
AND $__filter(ServiceName, $service)
AND $__conditionalAll(SeverityText NOT IN ($severity), $severity)
GROUP BY ts
ORDER BY ts ASC
```
### Stacked Bar 차트 — 심각도별 오류 건수
```sql theme={null}
SELECT
$__timeInterval(TimestampTime) AS ts,
lower(SeverityText),
count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
AND lower(SeverityText) IN ('error', 'warn')
AND $__filters
GROUP BY SeverityText, ts
ORDER BY ts ASC
```
### 테이블 차트 — 가장 느린 엔드포인트 상위 10개
```sql theme={null}
SELECT
SpanName AS endpoint,
avg(Duration) / 1000 AS avg_duration_ms,
count() AS request_count
FROM otel_traces
WHERE $__timeFilter(Timestamp)
AND $__filters
GROUP BY SpanName
ORDER BY avg_duration_ms DESC
LIMIT 10
```
### 파이 차트 — 서비스별 요청 분포
```sql theme={null}
SELECT
ServiceName,
count() AS request_count
FROM otel_traces
WHERE $__timeFilter(Timestamp)
AND $__filters
GROUP BY ServiceName
```
* `request_count` (숫자형)은 각 조각의 크기를 결정합니다.
* `ServiceName` (문자열)은 각 조각의 레이블을 지정합니다.
### 숫자 차트 — 전체 오류 수
```sql theme={null}
SELECT
count() AS total_errors
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
AND SeverityText = 'error'
AND $__filters
```
첫 번째 행의 숫자 값 `total_errors`가 표시됩니다.
## 참고 사항
* SQL 기반 시각화는 `readonly` 모드가 활성화된 상태로 실행되며, `SELECT` 쿼리만 허용됩니다.
* SQL 기반 시각화에는 SQL 쿼리가 정확히 하나만 포함되어야 하며, 여러 쿼리는 지원되지 않습니다.
* SQL Editor는 쿼리 매개변수와 매크로 모두에 대해 자동 완성 제안을 제공합니다.
* 대시보드 필터를 SQL 기반 시각화에 적용하려면 Source를 선택해야 합니다. 정확하게 필터링되도록 Source는 조회하는 테이블과 일치해야 합니다.
* 대시보드 변수에는 Source가 필요하지 않습니다. 값은 타일 자체의 Source가 아니라 대시보드의 필터 드롭다운에서 가져옵니다.
* 대시보드 변수를 참조하는 SQL 타일의 알림은 대시보드에서 선택한 값이 아니라 모든 변수가 비어 있는 상태에서 평가됩니다.