Schema 概览

ChainStream GraphQL schema 的结构 — Chain Groups、Cube 字段、生成类型与内省

​

动态 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 端点。

---

​

根查询结构

根查询类型名为 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!]!
    # ... more EVM Cubes
  }

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

  Trading(dataset: Dataset, aggregates: Aggregates) {
    Pairs(...): [PairsRecord!]!
    Tokens(...): [TokensRecord!]!
  }
}

不存在 Mutation 或 Subscription 类型——GraphQL API 为只读分析查询。

---

​

Chain Group

按目标区块链生态，Cube 分为三组：

Chain Group	network 参数	可用网络	说明
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。

---

​

Chain Group 参数

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

​

Dataset

dataset 控制查询数据的时间范围：

值	说明
combined	全量范围——同时包含近期与历史数据**（默认）**
realtime	仅近期数据（约最近 24 小时）
archive	历史数据，上限为保留 TTL

query {
  Solana(dataset: realtime) {
    DEXTrades(limit: {count: 10}, orderBy: {descending: Block_Time}) {
      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 专属 selector：

参数	类型	必填	说明
where	{Cube}Filter	否	与维度层级一致的嵌套筛选对象
limit	LimitInput	否	分页：{count: Int, offset: Int}
orderBy	{Cube}OrderBy	否	排序枚举（{Path}_ASC / {Path}_DESC）
selectors	筛选输入	否	快捷筛选（如 tokenAddress: {is: "..."}）

query {
  Solana {
    DEXTrades(
      tokenAddress: {is: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}
      where: { Block: { Time: { after: "2026-01-01T00:00:00Z" } } }
      limit: { count: 50, offset: 0 }
      orderBy: {descending: Block_Time}
    ) {
      Block { Time }
      Trade { Buy { Amount PriceInUSD } }
    }
  }
}

​

LimitInput

input LimitInput {
  count: Int   # Number of rows to return
  offset: Int  # Number of rows to skip (for pagination)
}

默认 count 因 Cube 而异（多为 25）。多数 Cube 最大为 10,000。

---

​

每个 Cube 的生成类型

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

Record 类型

{Cube}Record — 返回值类型，包含全部可选维度与指标。字段结构与 Cube 维度层级一致。

Filter 输入

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

OrderBy 枚举

{Cube}OrderBy — 每条维度路径在升序与降序下的枚举变体（如 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 查询探索类型、字段与参数：

列出所有 Cube

query {
  __schema {
    queryType {
      fields {
        name
        description
        args { name type { name } }
      }
    }
  }
}

查看某 Cube 类型

query {
  __type(name: "DEXTradesRecord") {
    name
    fields {
      name
      type { name kind ofType { name } }
    }
  }
}

列出筛选运算符

query {
  __type(name: "StringFilter") {
    name
    inputFields {
      name
      type { name kind }
    }
  }
}

GraphQL IDE 会自动拉取 introspection schema 以驱动自动补全与内联文档。可在界面中交互探索完整 schema，无需手写 introspection 查询。

---

​

下一步

数据 Cube

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

Chain Group

了解 EVM、Solana、Trading 三个 Chain Group 及其可用 Cube。

Dataset 与 Aggregates

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

筛选

学习如何用 where 与 selector 快捷方式收窄查询。

排序与分页

使用 orderBy 与 limit 对大数据集排序与分页。

指标与聚合

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