Schema 概览

动态 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
查看某 Cube 类型
列出筛选运算符

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

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 聚合数据。

快速开始

GraphQL IDE

Schema 与数据模型

查询示例

计费与额度

动态 Schema 生成

根查询结构

Chain Group

Chain Group 参数

Dataset

Aggregates

通用参数模式

LimitInput

每个 Cube 的生成类型

Record 类型

Filter 输入

OrderBy 枚举

Introspection

下一步

数据 Cube

Chain Group

Dataset 与 Aggregates

筛选

排序与分页

指标与聚合

​动态 Schema 生成

​根查询结构

​Chain Group

​Chain Group 参数

​Dataset

​Aggregates

​通用参数模式

​LimitInput

​每个 Cube 的生成类型

Record 类型

Filter 输入

OrderBy 枚举

​Introspection

​下一步

数据 Cube

Chain Group

Dataset 与 Aggregates

筛选

排序与分页

指标与聚合

动态 Schema 生成

根查询结构

Chain Group

Chain Group 参数

Dataset

Aggregates

通用参数模式

LimitInput

每个 Cube 的生成类型

Introspection

下一步