대시보드 작성#

대시보드는 dashboards/<slug>/page.md 문서와 필요한 경우 같은 디렉터리의 .sql, .tsx 파일로 구성됩니다. Markdown으로 설명을 작성하고, 컴포넌트로 이름이 지정된 쿼리 결과를 차트, 테이블, 숫자, 피벗, 지도로 표현합니다.

페이지 만들기#

dashboards/revenue/
  page.md
  revenue-daily.sql

프런트매터에 페이지 제목, 새로 고침 간격, 결과 상한, 선택 사항인 테마를 지정합니다.

---
title: Revenue
refresh: 4h
max_rows: 2000
theme: supernova
---

쿼리 추가#

페이지에서는 revenue-daily.sql을 revenue-daily로 참조합니다.

select
  cast(created_at as date) as day,
  sum(amount) / 100.0 as revenue
from titan.stripe.charges
where status = 'succeeded' and not _deleted
group by day
order by day

언어 이름으로 시작하는 인라인 펜스도 데이터 소스입니다: ``` `sql revenue-daily ```. 긴 쿼리는 같은 디렉터리의 파일로 분리하면 검토하기 쉽습니다.

다른 쿼리 활용#

쿼리는 같은 대시보드의 다른 쿼리를 queries.<name>으로 읽을 수 있습니다.

select sum(revenue) as revenue
from queries."revenue-daily"
where day >= $period.start

참조한 쿼리는 해당 이름을 사용한 위치에 인라인으로 삽입되므로 같은 작업 안에서 실행되며 항상 현재 데이터를 읽습니다. 두 쿼리 사이에 저장되는 데이터는 없습니다. $period.start 같은 입력은 어느 쿼리에서든 사용할 수 있습니다. 존재하지 않는 쿼리 참조나 두 쿼리 사이의 순환 참조는 페이지 위에 표시됩니다.

결과 렌더링#

<Chart data={revenue-daily} type="line" x="day" y="revenue"
       title="Revenue by day" format={{"type":"money","currency":"USD"}} />

내장 데이터 컴포넌트는 Chart, Table, BigNumber, Pivot, Map입니다. 차트 타입은 line, bar, area, donut, pie, scatter입니다. 관련 컴포넌트를 <Row> 안에 넣으면 같은 행에 배치됩니다.

목표 표시#

<Chart data={revenue-daily} type="bar" x="day" y="revenue"
       goal={{"y":120000,"label":"Target"}} />

goal은 값 축에 기준선을 그리고 선이 항상 플롯 안에 들어오도록 눈금을 확장합니다. 배열을 전달하면 최소 목표, 계획, 도전 목표 같은 기준선을 최대 4개까지 표시할 수 있습니다. 가로 막대 차트에서는 화면 방향이 아니라 값을 따르므로 기준선이 세로로 그려집니다. 도넛 차트와 원형 차트에는 값 축이 없으므로 이 속성을 허용하지 않습니다.

시리즈 하나 강조#

<Chart data={revenue-by-plan} type="line" x="day" y="revenue" series="plan" emphasis="enterprise" />

emphasis는 지정한 시리즈의 색상을 유지하고 나머지는 모두 흐린 색으로 표시합니다. 선, 영역, 막대, 점, 범례, 도구 설명의 색상 표시가 함께 바뀝니다. 이름은 대소문자를 구분하지 않습니다. 결과에 해당 이름의 시리즈가 없으면 아무것도 바뀌지 않으므로 데이터에서 범주가 사라져도 차트는 깨지지 않습니다.

특정 시점에 이름 붙이기#

<Chart data={revenue-daily} type="line" x="day" y="revenue"
       annotations={[{"x":"2026-03-01","label":"Price change"}]} />

각 주석은 해당 x 위치에 가는 세로선을 그리고 플롯 상단에 작은 레이블을 표시합니다. 주석은 최대 8개입니다. x는 쿼리가 실제로 반환한 값이어야 합니다. 필터로 표시 범위가 바뀌었을 때 범위 밖의 주석은 가장자리에 붙이지 않고 생략합니다. 레이블은 길이를 줄여 표시하며 겹치면 한 행 아래로 내려 배치합니다. 4행을 넘으면 선은 그리지만 레이블은 생략합니다. 5번째 텍스트 행은 플롯 영역을 차지하기 때문입니다.

숫자와 차트에 같은 쿼리 재사용#

<BigNumber data={revenue-daily} value="revenue" label="Revenue" agg="sum" trend />

큰 숫자 컴포넌트는 기본적으로 첫 행을 읽습니다. agg를 지정하면 대신 sum, avg, last, first로 열 전체를 집계합니다. 따라서 일별 쿼리의 같은 행들로 차트와 정확한 합계를 함께 표시할 수 있습니다. trend는 값 옆에 해당 열의 값을 행 순서대로 그린 스파크라인을 추가합니다.

정수 열의 합계는 부동소수점 합계에 오차가 생기는 범위를 넘어도 정확하므로 개수와 ID가 올바르게 유지됩니다. 기본 compact 형식은 표시 값을 여전히 반올림합니다. 간결하게 보여주기 위한 형식이기 때문입니다. 모든 자릿수가 중요하면 number 또는 integer를 사용하세요.

이전 기간과 비교#

<Chart data={revenue-daily} type="line" x="day" y="revenue" compare="prev-period" />
<BigNumber data={revenue-total} value="revenue" label="Revenue" compare="prev-year" />

compare는 날짜 범위를 과거로 옮겨 같은 쿼리를 다시 실행합니다. prev-period는 현재 기간의 길이만큼, prev-year는 달력 기준 1년만큼 옮깁니다. 차트는 현재 기간 아래에 이전 기간을 흐리게 그리고, 직접 부제목을 작성하지 않았다면 변화량을 설명 문구로 추가합니다. 큰 숫자 컴포넌트는 값 옆에 변화량을 표시합니다.

옮길 날짜 범위가 있으려면 쿼리가 날짜 범위를 읽어야 하므로 $period.start와 $period.end로 필터링하세요. 차트에서는 측정값 1개를 비교합니다. y 목록, series, 도넛 차트는 지원하지 않습니다. 큰 숫자 컴포넌트에서 compare는 delta를 대체합니다.

두 기간은 행 순서가 아닌 값으로 정렬됩니다. 날짜 축에서는 이전 기간의 각 행을 쿼리가 사용한 이동량만큼 정확히 앞으로 옮깁니다. 따라서 특정 날짜가 빠져 있으면 전체가 왼쪽으로 밀리지 않고 간격이 남습니다. 상위 N개 차트 같은 범주 축에서는 이전 기간의 행을 이름으로 대응시킵니다. 지난 기간에만 상위 N개에 있던 범주는 배치할 자리가 없어 그리지 않으며, 현재 기간에 새로 등장한 범주에는 이전 기간의 흐린 표시가 없습니다. 설명 문구의 변화량은 차트에 담지 못한 행을 포함해 이전 기간 전체를 기준으로 계산하므로, 그림이 일부만 보여주더라도 문구는 정확합니다.

타입이 지정된 입력 추가#

<DateRange name="period" default="-30d" />
<Select name="currency" options={["usd","eur","gbp"]} default="usd" />

SQL에서 입력을 $period.start, $period.end, $currency로 참조합니다. 값은 선언에 따라 검증되고 준비된 문장의 매개변수로 바인딩됩니다. URL 값은 SQL 문자열에 직접 삽입되지 않습니다.

TextInput, NumberInput, Select, DateRange를 지원합니다. multiple이 지정된 Select는 크기가 제한된 목록을 바인딩합니다. 상대 날짜 프리셋에는 -30d, -2w, -6m, -1y, mtd, ytd, today, all이 있습니다.

대시보드 확장#

페이지 전용 컴포넌트는 page.md 옆에 <Name>.tsx로 추가하고, 공유 컴포넌트는 dashboards/components/ 아래에 둡니다. 사용자 지정 컴포넌트는 범위가 제한된 테이블 데이터와 내장 컴포넌트와 동일한 테마 유틸리티를 받습니다.