> ## 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 中每個鏈組都接受兩個可選引數，用於控制 **查詢命中哪張底層表**。可按場景在新鮮度、查詢速度與資料完整性之間取捨。

***

## 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. 用 `dataset: archive` 與 `where` 從檢查點查到當前時間
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` 引數決定查詢是否使用 **預聚合物化檢視**（DWM 層），而非原始明細表（DWD 層）。預聚合表通常按分鐘預計算彙總，查詢明顯更快。

| 取值     | 說明                     | 典型場景            |
| :----- | :--------------------- | :-------------- |
| `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` | K 線已預計算，響應最快   |
| 成交量隨時間變化   | `aggregates: yes`  | 可利用預聚合成交量統計    |
| 單筆成交分析     | `aggregates: no`   | 需要彙總無法提供的逐事件細節 |
| 統計獨立交易者數   | `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` 利用預計算彙總，比全表掃描原始事件快幾個數量級。
  </Card>
</CardGroup>

<Tip>
  若要 OHLC 或成交量查詢儘可能快，可組合 `dataset: realtime` 與 `aggregates: only`，命中最小、最最佳化的一片資料。
</Tip>

***

## 相關文件

<CardGroup cols={2}>
  <Card title="Schema 概覽" icon="sitemap" href="/zh-Hant/graphql/schema/schema-overview">
    瞭解 dataset 與 aggregates 在整體查詢結構中的位置。
  </Card>

  <Card title="資料 Cubes" icon="cubes" href="/zh-Hant/graphql/schema/cubes">
    檢視哪些 Cube 支援 dataset 切換。
  </Card>
</CardGroup>