跳轉到主要內容

​
動態 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 聚合資料。