ChainStream GraphQL의 모든 체인 그룹은 어떤 기본 테이블을 쿼리할지 제어하는 두 개의 선택적 파라미터를 받습니다. 이 파라미터를 통해 사용 사례에 따라 최신성, 쿼리 속도, 데이터 완전성을 최적화할 수 있습니다.
Dataset 파라미터
dataset 파라미터는 쿼리되는 데이터의 시간 범위를 제어합니다. 쿼리가 실시간 테이블, 아카이브 테이블, 또는 둘 다를 조회할지 결정합니다.
| 값 | 설명 | 일반적인 사용 사례 |
|---|
combined | 실시간 및 아카이브 데이터 모두 쿼리 (기본값) | 전체 범위가 필요한 범용 쿼리 |
realtime | 최근 데이터만 (약 최근 24시간) | 모니터링 대시보드, 최근 트레이드, 실시간 알림 |
archive | 보존 TTL까지의 과거 데이터만 | 과거 분석, 백필, 추세 연구 |
사용법
query {
Solana(dataset: realtime) {
DEXTrades(limit: {count: 10}, orderBy: Block_Time_DESC) {
Block { Time }
Trade { Buy { Currency { MintAddress } Amount PriceInUSD } }
}
}
}
query {
EVM(network: eth, dataset: archive) {
Transfers(
where: { Block: { Time: { after: "2026-01-01T00:00:00Z", before: "2026-02-01T00:00:00Z" } } }
limit: {count: 100}
) {
Block { Time }
Transfer { Currency { MintAddress } Amount AmountInUSD }
}
}
}
과거 데이터 백필
데이터 파이프라인을 구축하거나 다운타임에서 복구할 때 dataset: archive와 시간 범위 필터를 사용하여 과거 데이터를 백필할 수 있습니다:
- 마지막으로 처리된 타임스탬프 또는 블록 높이를 기록
- 마지막 체크포인트부터 현재 시간까지의
where 필터와 함께 dataset: archive를 쿼리
- 백필된 데이터 처리
- 지속적인 모니터링을 위해
dataset: realtime으로 전환
query BackfillTrades {
Solana(dataset: archive) {
DEXTrades(
where: {
Block: {
Time: {
after: "2026-04-01T00:00:00Z"
before: "2026-04-02T00:00:00Z"
}
}
}
limit: {count: 10000}
orderBy: Block_Time_ASC
) {
Block { Time Slot }
Transaction { Hash }
Trade {
Buy { Currency { MintAddress } Amount PriceInUSD }
Sell { Currency { MintAddress } Amount }
}
}
}
}
Dataset 미지원 테이블
일부 Cube는 dataset 값에 관계없이 항상 동일한 테이블을 쿼리합니다:
- DWS Cube:
TokenHolders, WalletTokenPnL, DEXPools — 현재 상태 스냅샷을 나타냄
- 특수 테이블:
TransactionBalances, PredictionTrades, PredictionManagements, PredictionSettlements
이러한 Cube에서는 dataset이 조용히 무시됩니다.
Aggregates 파라미터
aggregates 파라미터는 쿼리가 원시 상세 테이블(DWD 레이어) 대신 사전 집계된 매터리얼라이즈드 뷰(DWM 레이어)를 사용할지 제어합니다. 사전 집계 테이블은 사전 계산된 롤업(일반적으로 분별)을 포함하여 쿼리 속도가 크게 빨라집니다.
| 값 | 설명 | 일반적인 사용 사례 |
|---|
yes | 가능한 경우 사전 집계 테이블 우선 사용 (기본 동작) | 대부분의 분석 쿼리 |
no | 원시 상세 테이블만 사용 | 이벤트별 세분화가 필요한 경우 |
only | 사전 집계 테이블만 사용 | 최대 쿼리 속도, 제한된 필드 세트 허용 |
사용법
query {
EVM(network: eth, aggregates: only) {
Pairs(
where: { Token: { Address: { is: "0xdac17f958d2ee523a2206206994597c13d831ec7" } } }
limit: {count: 100}
orderBy: Block_Time_DESC
) {
Interval { Time }
Price { Ohlc { Open High Low Close } }
Volume { Usd }
}
}
}
모드별 사용 시점
| 시나리오 | 권장 | 이유 |
|---|
| OHLC 차트 구축 | aggregates: only | 사전 계산된 캔들스틱 데이터, 가장 빠른 응답 |
| 시간별 거래량 추세 | aggregates: yes | 사전 집계된 거래량 통계 활용 |
| 개별 트레이드 분석 | aggregates: no | 롤업이 제공하지 않는 이벤트별 세부 정보 필요 |
| 고유 트레이더 수 | aggregates: yes | 사전 계산된 고유 수 사용 가능 |
두 파라미터 결합
dataset과 aggregates를 함께 사용할 수 있습니다:
query {
Trading(dataset: realtime, aggregates: yes) {
Tokens(
where: { Token: { Address: { is: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } } }
limit: {count: 60}
orderBy: Block_Time_DESC
) {
Interval { Time }
Volume { Usd BuyVolumeUSD SellVolumeUSD }
Stats { TradeCount UniqueBuyers UniqueSellers }
}
}
}
성능 고려사항
대시보드에는 realtime 사용
dataset: realtime은 더 작은 테이블 파티션을 쿼리하여 모니터링 사용 사례에 더 빠른 응답 시간을 제공합니다.
분석에는 aggregates 사용
aggregates: yes 또는 only는 원시 이벤트 테이블을 스캔하는 것보다 수 배 빠른 사전 계산된 롤업을 활용합니다.
가장 빠른 OHLC 또는 거래량 쿼리를 위해 dataset: realtime과 aggregates: only를 결합하세요. 가장 작고 가장 최적화된 데이터 슬라이스를 대상으로 합니다.
관련 문서
스키마 개요
전체 쿼리 구조에서 dataset과 aggregates가 어떻게 맞는지 확인하세요.
데이터 큐브
어떤 Cube가 dataset 전환을 지원하는지 확인하세요.
