スキーマ概要

動的スキーマ生成

ChainStream GraphQL スキーマは起動時に activecube-rs によって動的に生成されます。activecube-rs は Rust のライブラリで、Cube 定義を完全に型付けされた async-graphql スキーマにコンパイルします。各 Cube は OLAP テーブルに裏付けられた分析データモデルに対応し、activecube-rs が自動的に次を生成します。

Cube 用のトップレベル Query フィールド（所属する Chain Group の下にネスト）
選択可能なディメンションを表す Record 型（{Cube}Record）
ディメンション階層に対応する Filter 入力（{Cube}Filter）
すべてのディメンションパスに対する ASC/DESC バリアントを持つ OrderBy 列挙（{Cube}OrderBy）

スキーマは常に下位のデータモデルと一致するため、手書きの SDL を保守する必要はありません。

スキーマは Cube 定義から生成されるため、Rust で新しいデータモデルを追加するとデプロイ後に GraphQL エンドポイントへ自動的に反映されます。

ルート Query の構造

ルートのクエリ型名は ChainStream です。Cube は 3 つの 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 は対象とするブロックチェーンエコシステムに応じて 3 グループに分かれます:

Chain Group	`network` 引数	利用可能なネットワーク	説明
EVM	必須	`eth`, `bsc`, `polygon`	すべての EVM 互換チェーン向けの共通 Cube
Solana	不要	`sol`（暗黙）	Instructions、DEXOrders などチェーン固有 Cube を含む Solana 向け
Trading	不要	クロスチェーン（`sol`, `eth`, `bsc`）	事前集計の取引分析（OHLC ローソク、トークン統計）。データ内に `chain` ディメンションあり

EVM グループは、問い合わせるチェーンを選ぶために network 引数が必要です。Solana と Trading には network 引数は不要です — Solana は暗黙で、Trading はデータ内に chain ディメンションがあります。

各グループにどの Cube が属するかの詳細は Chain Groups を参照してください。

Chain Group のパラメータ

すべての Chain Group は、データソースの挙動を制御する 2 つの任意パラメータを受け取ります。

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 固有の任意のセレクターを受け取ります:

引数	型	必須	説明
`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 は 3 つの関連型を生成します:

Record 型

{Cube}Record — 選択可能なすべてのディメンションとメトリクスを含む戻り値の型。フィールド構造は Cube のディメンション階層を反映します。

Filter 入力

{Cube}Filter — 各ディメンションがフィルターprimitive（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
  # ...
}

イントロスペクション

スキーマは標準の GraphQL イントロスペクションをサポートします。__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 はイントロスペクションスキーマを自動取得し、オートコンプリートとインライン文書を提供します。イントロスペクションクエリを手で書かなくても、対話的にスキーマ全体を探索できます。

次のステップ

Data Cubes

25 の Cube — フィールド、セレクター、データウェアハウス層を確認します。

Chain Groups

EVM、Solana、Trading の Chain Group と利用可能な Cube を理解します。

Dataset & Aggregates

dataset と aggregates でデータソースの範囲と事前集計の挙動を制御します。

フィルタリング

where フィルターとセレクター省略形でクエリを絞り込みます。

並び順とページネーション

orderBy と limit で結果を並べ替え、大きなデータセットをページングします。

メトリクスと集計

クエリ内で count、sum、avg、min、max、uniq を使ってデータを集計します。

はじめに

GraphQL IDE

スキーマとデータモデル

クエリ例

課金とクレジット

動的スキーマ生成

ルート Query の構造

Chain Group

Chain Group のパラメータ

Dataset

Aggregates

共通の引数パターン

LimitInput

Cube ごとに生成される型

Record 型

Filter 入力

OrderBy 列挙

イントロスペクション

次のステップ

Data Cubes

Chain Groups

Dataset & Aggregates

フィルタリング

並び順とページネーション

メトリクスと集計

​動的スキーマ生成

​ルート Query の構造

​Chain Group

​Chain Group のパラメータ

​Dataset

​Aggregates

​共通の引数パターン

​LimitInput

​Cube ごとに生成される型

Record 型

Filter 入力

OrderBy 列挙

​イントロスペクション

​次のステップ

Data Cubes

Chain Groups

Dataset & Aggregates

フィルタリング

並び順とページネーション

メトリクスと集計

動的スキーマ生成

ルート Query の構造

Chain Group

Chain Group のパラメータ

Dataset

Aggregates

共通の引数パターン

LimitInput

Cube ごとに生成される型

イントロスペクション

次のステップ