数据集与聚合

使用 dataset 与 aggregates 参数控制数据源范围与预聚合行为

​

概述

ChainStream GraphQL 中每个链组都接受两个可选参数，用于控制 查询命中哪张底层表。可按场景在新鲜度、查询速度与数据完整性之间取舍。

---

​

Dataset 参数

dataset 参数控制所查数据的 时间范围，决定走实时表、归档表或两者。

取值	说明	典型场景
combined	同时查询实时与归档数据 （默认） — 通常覆盖最近约 7–10 天	需要完整时间范围的通用查询
realtime	仅近期数据（约最近 24 小时）	监控大盘、最新成交、实时告警
archive	仅保留窗口内的历史数据（约 7–10 天）	历史分析、回补、趋势研究

​

用法

query {
  Solana(dataset: realtime) {
    DEXTrades(limit: {count: 10}, orderBy: {descending: Block_Time}) {
      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 配合时间范围过滤回补历史：

1. 记录上次处理的时间戳或区块高度
2. 用 dataset: archive 与 where 从检查点查到当前时间
3. 处理回补数据
4. 持续监控时改用 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: {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	仅使用预聚合表	追求最快速度，可接受字段集受限

​

用法

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：

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 分钟的跨链代币成交统计，以获得较高速度。

---

​

性能考量

大盘用 realtime

dataset: realtime 命中更小的表分区，监控类场景响应更快。

分析用 aggregates

aggregates: yes 或 only 利用预计算汇总，比全表扫描原始事件快几个数量级。

若要 OHLC 或成交量查询尽可能快，可组合 dataset: realtime 与 aggregates: only，命中最小、最优化的一片数据。

---

​

相关文档

Schema 概览

了解 dataset 与 aggregates 在整体查询结构中的位置。

数据 Cubes

查看哪些 Cube 支持 dataset 切换。