> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 데이터셋 및 집계

> dataset 및 aggregates 파라미터로 데이터 소스 범위와 사전 집계 동작 제어

## 개요

ChainStream GraphQL의 모든 Chain Group은 **어떤 기본 테이블을 조회할지** 제어하는 선택 파라미터 두 개를 받습니다. 사용 사례에 따라 신선도, 쿼리 속도, 데이터 완전성을 맞출 수 있습니다.

***

## Dataset 파라미터

`dataset` 파라미터는 조회 데이터의 **시간 범위**를 제어합니다. 실시간 테이블, 아카이브 테이블, 또는 둘 다를 칠지 결정합니다.

| 값          | 설명                                               | 일반적인 사용                  |
| :--------- | :----------------------------------------------- | :----------------------- |
| `combined` | 실시간·아카이브 데이터 **모두** 조회 **(기본값)** — 보통 최근 약 7–10일 | 전체 범위가 필요한 범용 쿼리         |
| `realtime` | 최근 데이터만(대략 지난 24시간)                              | 모니터링 대시보드, 최신 거래, 실시간 알림 |
| `archive`  | 보존 기간(\~7–10일) 내 역사 데이터만                         | 역사 분석, 백필, 트렌드 조사        |

### 사용법

```graphql theme={null}
query {
  Solana(dataset: realtime) {
    DEXTrades(limit: {count: 10}, orderBy: {descending: Block_Time}) {
      Block { Time }
      Trade { Buy { Currency { MintAddress } Amount PriceInUSD } }
    }
  }
}
```

```graphql theme={null}
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`와 시간 범위 필터로 역사 데이터를 백필할 수 있습니다.

1. 마지막으로 처리한 타임스탬프 또는 블록 높이를 기록합니다.
2. 마지막 체크포인트부터 현재까지 `where` 필터와 함께 `dataset: archive`로 쿼리합니다.
3. 백필된 데이터를 처리합니다.
4. 지속 모니터링에는 `dataset: realtime`으로 전환합니다.

```graphql theme={null}
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: {ascending: Block_Time}
    ) {
      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) 대신 **사전 집계 materialized view**(DWM 레이어)를 쓸지 결정합니다. 사전 집계 테이블에는 보통 분 단위로 미리 계산된 rollup이 들어 있어 훨씬 빠르게 조회할 수 있습니다.

| 값      | 설명                            | 일반적인 사용               |
| :----- | :---------------------------- | :-------------------- |
| `yes`  | 가능하면 사전 집계 테이블 사용 **(기본 동작)** | 대부분의 분석 쿼리            |
| `no`   | 원시 상세 테이블만 사용                 | 이벤트 단위 세분도가 필요할 때     |
| `only` | 사전 집계 테이블만 사용                 | 최대 속도, 선택 가능한 필드는 제한적 |

### 사용법

```graphql theme={null}
query {
  EVM(network: eth, aggregates: only) {
    Pairs(
      where: { Token: { Address: { is: "0xdac17f958d2ee523a2206206994597c13d831ec7" } } }
      limit: {count: 100}
      orderBy: {descending: Block_Time}
    ) {
      Interval { Time }
      Price { Ohlc { Open High Low Close } }
      Volume { Usd }
    }
  }
}
```

### 모드별 선택 가이드

| 시나리오          | 권장                 | 이유                      |
| :------------ | :----------------- | :---------------------- |
| OHLC 차트 작성    | `aggregates: only` | 사전 계산 캔들 데이터, 가장 빠른 응답  |
| 시간에 따른 거래량 추이 | `aggregates: yes`  | 사전 집계 거래량 통계 활용         |
| 개별 거래 분석      | `aggregates: no`   | rollup에 없는 이벤트 단위 상세 필요 |
| 고유 트레이더 수 집계  | `aggregates: yes`  | 사전 계산된 고유 카운트 활용 가능     |

***

## 두 파라미터 함께 쓰기

`dataset`과 `aggregates`를 동시에 사용할 수 있습니다.

```graphql theme={null}
query {
  Trading(dataset: realtime, aggregates: yes) {
    Tokens(
      where: { Token: { Address: { is: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } } }
      limit: {count: 60}
      orderBy: {descending: Block_Time}
    ) {
      Interval { Time }
      Volume { Usd BuyVolumeUSD SellVolumeUSD }
      Stats { TradeCount UniqueBuyers UniqueSellers }
    }
  }
}
```

이 쿼리는 실시간 데이터와 사전 집계 테이블을 함께 사용해, 최근 약 60분간의 크로스체인 토큰 거래 통계를 최대한 빠르게 가져옵니다.

***

## 성능 고려 사항

<CardGroup cols={2}>
  <Card title="대시보드에는 realtime" icon="gauge-high">
    `dataset: realtime`은 더 작은 테이블 파티션을 조회해 모니터링 용도에서 응답이 빨라집니다.
  </Card>

  <Card title="분석에는 aggregates" icon="chart-line">
    `aggregates: yes` 또는 `only`는 원시 이벤트 테이블 풀스캔보다 수 배 빠른 사전 계산 rollup을 사용합니다.
  </Card>
</CardGroup>

<Tip>
  OHLC나 거래량 쿼리를 최대한 빠르게 하려면 `dataset: realtime`과 `aggregates: only`를 함께 쓰세요. 가장 작고 최적화된 데이터 슬라이스를 겨냥합니다.
</Tip>

***

## 관련 문서

<CardGroup cols={2}>
  <Card title="스키마 개요" icon="sitemap" href="/ko/graphql/schema/schema-overview">
    dataset과 aggregates가 전체 쿼리 구조에서 어떻게 맞는지 확인합니다.
  </Card>

  <Card title="데이터 Cube" icon="cubes" href="/ko/graphql/schema/cubes">
    dataset 전환이 지원되는 Cube를 확인합니다.
  </Card>
</CardGroup>