> ## 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="/cn/graphql/schema/schema-overview">
    了解 dataset 与 aggregates 在整体查询结构中的位置。
  </Card>

  <Card title="数据 Cubes" icon="cubes" href="/cn/graphql/schema/cubes">
    查看哪些 Cube 支持 dataset 切换。
  </Card>
</CardGroup>