> ## 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 は、**どの基盤テーブルに問い合わせるか** を制御する任意パラメータを 2 つ受け取ります。用途に応じて鮮度、クエリ速度、データの網羅性を最適化できます。

***

## `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）ではなく **事前集計済みマテリアライズドビュー**（DWM レイヤー）を使うかどうかを制御します。事前集計テーブルには通常 1 分単位で事前計算されたロールアップが含まれ、クエリがはるかに高速です。

| 値      | 説明                               | 典型的な用途                 |
| :----- | :------------------------------- | :--------------------- |
| `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`   | ロールアップにないイベント単位の詳細が必要 |
| ユニークトレーダー数の集計 | `aggregates: yes`  | 事前計算済みのユニーク数が利用可能     |

***

## 2 つのパラメータの併用

`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` は、生イベントテーブルをフルスキャンするより桁違いに速い事前計算ロールアップを使います。
  </Card>
</CardGroup>

<Tip>
  OHLC や出来高クエリを最速にしたい場合は、`dataset: realtime` と `aggregates: only` を組み合わせます。最も小さく最適化されたデータスライスを狙えます。
</Tip>

***

## 関連ドキュメント

<CardGroup cols={2}>
  <Card title="スキーマ概要" icon="sitemap" href="/jp/graphql/schema/schema-overview">
    `dataset` と `aggregates` が全体のクエリ構造のどこに位置するかを確認します。
  </Card>

  <Card title="データ Cube" icon="cubes" href="/jp/graphql/schema/cubes">
    どの Cube が `dataset` 切り替えに対応しているかを確認します。
  </Card>
</CardGroup>