본문으로 건너뛰기
버전: v0.3.0

데이터 설정

위젯에 실제 데이터를 연결하고 시각화하는 방법을 설명합니다. D.Hub 대시보드는 두 가지 데이터 모드를 지원합니다.

데이터 소스​

D.Hub 대시보드는 분석 데이터베이스를 통해 데이터를 조회합니다. D.Hub에 등록된 데이터셋은 자동으로 분석 테이블로 동기화되어 빠른 분석 쿼리가 가능합니다.

간단 모드 (Simple Mode)​

간단 모드

설정 방법​

  1. 데이터 소스 선택: 연결할 데이터셋을 선택합니다.
  2. 메트릭(Metric) 설정:
    • 값 필드: 시각화할 데이터 필드를 선택합니다. (예: price, count)
    • 집계 방식: SUM, AVG, COUNT, MIN, MAX 중 선택합니다.
  3. 그룹화 (Group By): 데이터를 그룹화할 기준 필드를 선택합니다. (예: category, date)
    • X축/Y축: 차트 유형에 따라 축에 매핑될 필드를 지정합니다.

지원 집계 함수​

함수설명예시
SUM합계총 매출액
AVG평균평균 주문 금액
COUNT개수주문 건수
MIN최소값최저 가격
MAX최대값최고 가격

쿼리 모드 (Query Mode) — SQL 에디터 + AI 어시스턴트​

쿼리 모드

SQL AI 어시스턴트

SQL 쿼리를 직접 작성하여 복잡한 데이터 가공이 필요한 경우 사용합니다. 구문 강조와 자동완성을 지원하는 SQL 에디터에서 작성합니다.

기본 사용법​

  1. 데이터 모드를 SQL로 변경합니다.
  2. SQL 에디터에 쿼리를 작성합니다 — SQL 구문 강조, 데이터셋 컬럼 자동완성, 줄 번호, Cmd/Ctrl+Enter 실행, 쿼리 히스토리, SELECT-only 검증을 지원합니다.
  3. 쿼리 테스트(Test Query) 버튼으로 결과를 미리 확인합니다. 실행 시간과 조회된 행 수가 표시됩니다.
  4. 결과 컬럼을 X축, Y축 등 차트 속성에 매핑합니다.

SQL 와이드 모달 편집기​

구성 패널(기본 320px)의 좁은 폭이 SQL 작성에 부족할 때, SQL 라벨 옆의 편집기 펼치기 아이콘으로 모달 형태의 와이드 편집기(최대 960px 폭 × 약 60vh, 최대 480px 높이)를 열 수 있습니다.

  • 와이드 편집기는 컴팩트 패널과 동일한 SQL 에디터·초기화·쿼리 테스트·결과/오류 표시를 제공합니다.
  • 모달을 닫으면 컴팩트 편집기와 내용이 자동 동기화됩니다.
  • AI escalation: 컴팩트 편집기에서 AI를 트리거하면(어시스턴트 아이콘, Cmd/Ctrl+I, 선택 메뉴) 와이드 모달이 자동으로 열리고 동일한 AI 모드로 자동 진입합니다. 선택 영역은 line/column 좌표로 보존되어 와이드 모달에서 같은 영역을 대상으로 계속 작업할 수 있습니다.

SQL 초기화 버튼​

SQL 라벨 옆의 초기화 버튼은 현재 SQL을 사용자의 Simple 설정 기반 SQL로 되돌립니다.

  • Simple 설정이 비어 있으면 데이터셋 스키마 기반 기본 템플릿(타입별 첫 번째 컬럼)으로 fallback합니다.
  • 활성 DRS 시간 범위가 있고 위젯에 dateFilterColumn이 설정되어 있으면, 초기화된 SQL에도 동일한 WHERE 절이 다시 주입됩니다 — 작성 중 손상된 SQL을 안전하게 회복할 수 있습니다.

AI 어시스턴트​

코드 편집기와 동일한 인라인 AI 흐름을 사용합니다.

  • 인라인 AI: ⌘I / Ctrl+I로 자연어 프롬프트를 열어 SQL을 생성·수정할 수 있습니다. (⌘K / Ctrl+K는 전역 검색이므로 혼동하지 마세요.)
  • 선택 영역 편집: SQL 일부를 선택하면 그 부분만 AI가 다듬도록 요청할 수 있습니다.
  • Accept / Reject: 제안된 SQL은 검토 후 수락 또는 거부합니다.
  • 컨텍스트 주입: 대시보드 SQL의 AI 어시스턴트는 가상 input 테이블이 아닌 실제 database.table과 데이터셋 컬럼 목록(이름·타입) 을 시스템 프롬프트로 받습니다. 생성되는 SQL이 위젯 컨텍스트의 정확한 식별자와 스키마를 반영합니다.

Simple → SQL 동기화​

간단 모드의 선택은 SQL로 자동 변환됩니다. Simple → SQL로 전환할 때 사용자가 간단 모드에서 직접 고른 데이터셋·필드·집계는 유지되며, SQL을 직접 수정한 뒤 다시 Simple로 돌아오면 변환 가능한 부분만 매핑됩니다(불일치 부분은 안내 메시지로 표시).

쿼리 예시​

-- 카테고리별 매출 합계
SELECT 
    category, 
    SUM(amount) as total 
FROM sales_data 
GROUP BY category
ORDER BY total DESC

-- 일별 주문 추이
SELECT 
    toDate(order_date) as date,
    COUNT(*) as order_count,
    SUM(amount) as revenue
FROM orders
GROUP BY date
ORDER BY date

-- 시간대별 트래픽 분석
SELECT 
    toHour(timestamp) as hour,
    COUNT(*) as visits
FROM page_views
WHERE toDate(timestamp) = today()
GROUP BY hour
ORDER BY hour

유용한 SQL 함수​

더 많은 함수가 필요하다면

전체 SQL 함수 레퍼런스는 참조 > SQL 쿼리 가이드를 참고하세요.

함수설명예시
toDate()날짜 변환toDate(timestamp)
toHour()시간 추출toHour(timestamp)
today()오늘 날짜WHERE date = today()
yesterday()어제 날짜WHERE date = yesterday()
toStartOfWeek()주 시작일toStartOfWeek(date)
toStartOfMonth()월 시작일toStartOfMonth(date)
formatDateTime()날짜 포맷팅formatDateTime(date, '%Y-%m')

DRS (Dashboard Range Selector) — 전역 날짜 범위​

상단 툴바의 DRS (Dashboard Range Selector) 는 대시보드 전역 날짜 범위입니다. 별도의 Date Range 위젯을 캔버스에 두지 않아도, 위젯에 명시적 시간 컬럼/범위 설정이 없는 경우 DRS의 값이 자동으로 위젯 쿼리에 주입됩니다. 위젯별로 별도 기간을 잠가야 할 때만 위젯 설정에서 명시합니다.

설정 방법​

  1. 캔버스 상단 DRS에서 프리셋(최근 7일·30일·사용자 지정) 또는 사용자 지정 범위를 선택합니다.
  2. 각 위젯의 데이터 설정에서 시간 컬럼이 자동 추론되면 별도 설정 없이 DRS가 적용됩니다.
  3. 위젯이 시간 컬럼을 추론하지 못하는 경우(예: 비정형 스키마), 위젯 데이터 설정의 Date Filter Column 에서 컬럼을 명시합니다.

시간 컬럼 자동 추론 규칙 (Simple 모드)​

위젯의 raw 쿼리는 변경되지 않으며, fetch 시점에 다음 우선순위로 시간 컬럼을 결정하여 WHERE 절을 동적으로 합성합니다.

  1. 구성 패널에서 사용자가 명시 설정한 Date Filter Column
  2. 차트의 X축 컬럼(labelColumn)이 다음 이름 패턴 중 하나와 단어 경계 매칭되면 그것: date · time · timestamp · datetime · created_at · updated_at · event_time · ts
  3. 위 두 단계 모두 해당 없음 → 시간 필터를 주입하지 않습니다 (위젯이 DRS 범위를 받지 않음).

추론이 적용된 위젯의 구성 패널 SQL 미리보기에는 "DRS 시간 범위 자동 적용됨" hint가 표시됩니다.

DRS 잠금과 자동 새로고침​

  • DRS를 사용자 지정 고정 범위로 잠그면, 시청자가 특정 시점을 분석 중이라고 판단하여 자동 새로고침이 비활성화됩니다.
  • DRS가 프리셋(최근 7일 등 상대 범위)일 때만 자동 새로고침이 작동합니다.

쿼리 모드에서 날짜 필터 사용​

쿼리 모드(SQL 직접 작성)에서는 시스템이 X축 등을 보고 시간 컬럼을 추론하지 않습니다. DRS 시간 범위를 적용하려면 위젯 설정의 날짜 필터 기준 컬럼(Date Filter Column)을 직접 지정합니다.

  • 구성 패널에서 DRS 범위가 바뀌면, 지정한 컬럼을 기준으로 위젯 SQL의 날짜 조건이 자동으로 갱신됩니다.
  • 해당 컬럼에 이미 >= … AND < … 형태의 날짜 조건이 있으면 날짜 값만 교체하고, 없으면 WHERE <col> >= … AND <col> < … 절을 새로 추가합니다.
-- order_date 를 '날짜 필터 기준 컬럼' 으로 지정하면
-- DRS 범위 변경 시 아래 WHERE 의 날짜 값이 자동으로 갱신됩니다.
SELECT
    toDate(order_date) as date,
    SUM(amount) as revenue
FROM orders
WHERE order_date >= '2026-06-01' AND order_date < '2026-06-08'
GROUP BY date
ORDER BY date
주의

SQL 모드는 자동 컬럼 추론에서 제외됩니다. 간단 모드와 달리, X축이 시간 컬럼이라는 이유만으로 WHERE 절이 자동 주입되지 않습니다. 서브쿼리·CTE·JOIN·윈도우 함수가 섞인 SQL에 시스템이 임의로 WHERE를 끼워 넣으면 "내가 쓴 쿼리와 실행되는 쿼리가 다른" 디버깅 함정이 생기기 때문입니다.

데이터 새로고침​

대시보드 데이터는 자동 새로고침(주기마다 자동)과 수동 새로고침(즉시) 두 가지로 갱신합니다. 두 방식 모두 대시보드의 모든 위젯이 동시에 데이터를 다시 조회하도록 새로고침 신호를 보냅니다.

자동 새로고침​

  • 주기 설정 위치: 대시보드 뷰어 상단 툴바의 자동 새로고침 드롭다운, 또는 편집기의 설정(Settings) 모달에서 지정합니다. 선택지는 비활성 / 30초 / 1분 / 5분 / 10분 / 30분이며, 이전에 저장된 사용자 지정 값이 있으면 그 항목도 함께 표시됩니다.
  • 동작 방식: 뷰어가 설정한 주기마다 새로고침 신호를 보내고, 대시보드의 모든 위젯이 이를 받아 데이터를 동시에 다시 조회합니다. 새로고침이 일어날 때 드롭다운의 시계 아이콘이 잠깐 회전해 갱신 시점을 알려줍니다.
  • 저장과 적용: 주기를 바꾸면 대시보드에 저장됩니다(대시보드가 저장되었습니다 알림). 뷰어 툴바에서 바꾼 값은 즉시 적용되고, 편집기 설정 모달에서 바꾼 값은 다음에 뷰어로 열 때 적용됩니다.

수동 새로고침​

뷰어 상단 툴바의 새로고침 버튼(↻)을 클릭하면 즉시 갱신합니다. 이때 대시보드 정의를 다시 불러온 뒤 모든 위젯의 데이터를 다시 조회하고, 데이터가 새로고침되었습니다 알림을 표시합니다. 수동 새로고침은 아래 DRS 잠금과 무관하게 항상 사용할 수 있습니다.

DRS 잠금 시 자동 새로고침 비활성화​

DRS(전역 날짜 범위)가 사용자 지정 고정 범위로 설정되어 있으면 자동 새로고침이 비활성화됩니다 — 시청자가 특정 시점을 분석 중이라고 보기 때문입니다. 이때 자동 새로고침 드롭다운은 비활성 상태가 되고, 자동 새로고침을 쓰려면 날짜 범위를 프리셋(최근 7일 등 상대 범위)으로 바꾸라는 안내 툴팁이 표시됩니다.