跳转到主要内容

​
动态 Schema 生成

ChainStream GraphQL Schema 在启动时由 activecube-rs（Rust 库）动态生成，该库将 Cube 定义编译为类型完整的 async-graphql Schema。每个 Cube 对应一个由 OLAP 表支撑的分析数据模型，activecube-rs 会自动生成：
  • 该 Cube 的 顶层 Query 字段（嵌套在其 Chain Group 下）
  • 表示可选维度的 Record 类型（{Cube}Record）
  • 与维度层级匹配的 Filter 输入（{Cube}Filter）
  • 每个维度路径的 ASC/DESC 变体组成的 OrderBy 枚举（{Cube}OrderBy）
因此 Schema 始终与底层数据模型一致，无需维护手写的 SDL 文件。
由于 Schema 由 Cube 定义生成，在 Rust 中新增任意数据模型后，部署即可在 GraphQL 端点中自动反映。

​
根 Query 结构

根查询类型名为 ChainStream。Cube 按三个 Chain Group 组织，各自作为顶层字段暴露： 
type ChainStream {
  EVM(network: Network!, dataset: Dataset, aggregates: Aggregates) {
    DEXTrades(...): [DEXTradesRecord!]!
    Transfers(...): [TransfersRecord!]!
    BalanceUpdates(...): [BalanceUpdatesRecord!]!
    Blocks(...): [BlocksRecord!]!
    Transactions(...): [TransactionsRecord!]!
    Events(...): [EventsRecord!]!
    Calls(...): [CallsRecord!]!
    # ... 更多 EVM Cube
  }

  Solana(dataset: Dataset, aggregates: Aggregates) {
    DEXTrades(...): [DEXTradesRecord!]!
    Instructions(...): [InstructionsRecord!]!
    DEXOrders(...): [DEXOrdersRecord!]!
    # ... 更多 Solana Cube
  }

  Trading(dataset: Dataset, aggregates: Aggregates) {
    Pairs(...): [PairsRecord!]!
    Tokens(...): [TokensRecord!]!
  }
}
不存在 Mutation 或 Subscription 类型 — GraphQL API 为只读分析查询。

​
Chain Group

Cube 按目标区块链生态分为三组：
Chain Groupnetwork 参数可用网络说明
EVM必填eth、bsc、polygon适用于所有 EVM 兼容链的共享 Cube
Solana不需要sol（隐式）Solana 专属 Cube，含链特有的 Instructions、DEXOrders 等
Trading不需要跨链（sol、eth、bsc）预聚合交易分析（OHLC K 线、代币统计），数据内含 chain 维度
EVM 组需要 network 参数来选择要查询的链。Solana 和 Trading 不需要 network 参数 — Solana 为隐式，Trading 数据内包含 chain 维度。
详见 Chain Groups 了解每个组包含哪些 Cube。

​
Chain Group 参数

每个 Chain Group 接受两个可选参数，控制数据源行为：

​
Dataset

dataset 参数控制查询的数据时间范围：
值说明
combined全量 — 同时查询近期与历史数据 （默认）
realtime仅近期数据（约最近 24 小时）
archive历史数据（至保留期限 TTL）
query {
  Solana(dataset: realtime) {
    DEXTrades(limit: {count: 10}, orderBy: Block_Time_DESC) {
      Block { Time }
      Trade { Buy { Amount } }
    }
  }
}

​
Aggregates

aggregates 参数控制是否使用预聚合（DWM/DWS）表：
值说明
yes优先使用预聚合表 （适用 Cube 的默认行为）
no仅使用原始明细表
only仅使用预聚合表（更快但字段有限）
query {
  Trading(aggregates: only) {
    Pairs(
      where: { Token: { Address: { is: "0x..." } } }
      limit: {count: 100}
    ) {
      Interval { Time }
      Price { Ohlc { Open High Low Close } }
      Volume { Usd }
    }
  }
}
详见 Dataset 与 Aggregates 了解用法、支持的表与性能指南。

​
通用参数模式

在 Chain Group 内部，每个 Cube 字段接受同一套标准参数，以及可选的 Cube 专属 selectors：
ArgumentTypeRequiredDescription
where{Cube}FilterNo与维度层级嵌套匹配的 Filter 对象
limitLimitInputNo分页：{count: Int, offset: Int}
orderBy{Cube}OrderByNo排序枚举（{Path}_ASC / {Path}_DESC）
selectorsFilter inputNo快捷筛选（例如 tokenAddress: {is: "..."}）
query {
  Solana {
    DEXTrades(
      tokenAddress: {is: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}
      where: { Block: { Time: { after: "2026-01-01T00:00:00Z" } } }
      limit: { count: 50, offset: 0 }
      orderBy: Block_Time_DESC
    ) {
      Block { Time }
      Trade { Buy { Amount PriceInUSD } }
    }
  }
}

​
LimitInput

input LimitInput {
  count: Int   # 返回行数
  offset: Int  # 跳过行数（用于分页）
}
默认 count 因 Cube 而异（常见为 25）。多数 Cube 最大为 10,000。

​
每个 Cube 的生成类型

对每个 Cube，activecube-rs 会生成三个配套类型：

Record 类型

{Cube}Record — 包含所有可选维度与指标的返回类型。字段结构镜像 Cube 的维度层级。

Filter 输入

{Cube}Filter — 嵌套输入对象，每个维度映射到 Filter 原语（StringFilter、IntFilter、DateTimeFilter 等）。

OrderBy 枚举

{Cube}OrderBy — 每个维度路径在 ASC 与 DESC 两个方向上的枚举变体（例如 Block_Time_ASC、Trade_Buy_Amount_DESC）。
以 DEXTrades 为例： 
# Record type (return shape)
type DEXTradesRecord {
  Block: DEXTradesBlockRecord
  Transaction: DEXTradesTransactionRecord
  Trade: DEXTradesTradeRecord
  Pool: DEXTradesPoolRecord
  IsSuspect: Boolean
  count: Int
  sum(of: DEXTradesSumOf!): Float
}

# Filter input
input DEXTradesFilter {
  Block: DEXTradesBlockFilter
  Transaction: DEXTradesTransactionFilter
  Trade: DEXTradesTradeFilter
  Pool: DEXTradesPoolFilter
  IsSuspect: BoolFilter
  any: [DEXTradesFilter!]  # OR logic
}

# OrderBy enum (partial)
enum DEXTradesOrderBy {
  Block_Time_ASC
  Block_Time_DESC
  Trade_Buy_Amount_ASC
  Trade_Buy_Amount_DESC
  # ...
}

​
Introspection

Schema 支持标准 GraphQL introspection。可使用 __schema 与 __type 查询探索类型、字段与参数： 
query {
  __schema {
    queryType {
      fields {
        name
        description
        args { name type { name } }
      }
    }
  }
}
GraphQL IDE 会自动拉取 introspection Schema 以提供自动补全与内联文档。无需手写 introspection 查询即可交互式浏览完整 Schema。

​
下一步

数据 Cube

浏览全部 25 个 Cube — 字段、selectors 与数仓分层。

Chain Groups

了解 EVM、Solana、Trading 三组的 Cube 分布。

Dataset 与 Aggregates

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

筛选

学习如何用 where Filter 与 selector 快捷方式缩小查询范围。

排序与分页

使用 orderBy 与 limit 对结果排序并分页遍历大数据集。

指标与聚合

在查询中使用 count、sum、avg、min、max、uniq 聚合数据。