> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema 概览

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

## 动态 Schema 生成

ChainStream GraphQL schema 在启动时由 **activecube-rs** **动态生成**。该 Rust 库将 **Cube** 定义编译为类型完整的 [async-graphql](https://github.com/async-graphql/async-graphql) schema。每个 Cube 对应由 OLAP 表支撑的分析数据模型，activecube-rs 会自动产出：

* Cube 的**顶层 Query 字段**（嵌套在其 Chain Group 下）
* 表示可选维度的 **Record 类型**（`{Cube}Record`）
* 与维度层级一致的 **Filter 输入**（`{Cube}Filter`）
* 每条维度路径的 ASC/DESC 变体组成的 **OrderBy 枚举**（`{Cube}OrderBy`）

因此 schema 始终与底层数据模型一致——无需手写 SDL 维护。

<Info>
  由于 schema 由 Cube 定义生成，Rust 中新增的数据模型在部署后会自动反映到 GraphQL 端点。
</Info>

***

## 根查询结构

根查询类型名为 `ChainStream`。Cube 归入三个 **Chain Group**，每个作为顶层字段暴露：

```graphql theme={null}
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` 维度    |

<Note>
  **EVM** 组必须传入 `network` 以选择链。**Solana** 与 **Trading** 不需要 `network`——Solana 为隐式，Trading 在数据内通过 `chain` 维度区分。
</Note>

完整划分见 [Chain Groups](/cn/graphql/schema/chain-groups)。

***

## Chain Group 参数

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

### Dataset

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

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

```graphql theme={null}
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` | 仅使用预聚合表（更快但字段受限）                    |

```graphql theme={null}
query {
  Trading(aggregates: only) {
    Pairs(
      where: { Token: { Address: { is: "0x..." } } }
      limit: {count: 100}
    ) {
      Interval { Time }
      Price { Ohlc { Open High Low Close } }
      Volume { Usd }
    }
  }
}
```

<Tip>
  详细用法、支持的表与性能建议见 [Dataset & Aggregates](/cn/graphql/schema/dataset-aggregates)。
</Tip>

***

## 通用参数模式

在 Chain Group 内，每个 Cube 字段接受同一套标准参数，外加可选的 Cube 专属 **selector**：

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

```graphql theme={null}
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

```graphql theme={null}
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 会生成三类配套类型：

<CardGroup cols={3}>
  <Card title="Record 类型" icon="table">
    `{Cube}Record` — 返回值类型，包含全部可选维度与指标。字段结构与 Cube 维度层级一致。
  </Card>

  <Card title="Filter 输入" icon="filter">
    `{Cube}Filter` — 嵌套输入对象，各维度映射到筛选原语（`StringFilter`、`IntFilter`、`DateTimeFilter` 等）。
  </Card>

  <Card title="OrderBy 枚举" icon="arrow-down-a-z">
    `{Cube}OrderBy` — 每条维度路径在升序与降序下的枚举变体（如 `Block_Time_ASC`、`Trade_Buy_Amount_DESC`）。
  </Card>
</CardGroup>

**DEXTrades 示例：**

```graphql theme={null}
# 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` 查询探索类型、字段与参数：

<Tabs>
  <Tab title="列出所有 Cube">
    ```graphql theme={null}
    query {
      __schema {
        queryType {
          fields {
            name
            description
            args { name type { name } }
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="查看某 Cube 类型">
    ```graphql theme={null}
    query {
      __type(name: "DEXTradesRecord") {
        name
        fields {
          name
          type { name kind ofType { name } }
        }
      }
    }
    ```
  </Tab>

  <Tab title="列出筛选运算符">
    ```graphql theme={null}
    query {
      __type(name: "StringFilter") {
        name
        inputFields {
          name
          type { name kind }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  [GraphQL IDE](https://ide.chainstream.io) 会自动拉取 introspection schema 以驱动自动补全与内联文档。可在界面中交互探索完整 schema，无需手写 introspection 查询。
</Tip>

***

## 下一步

<CardGroup cols={2}>
  <Card title="数据 Cube" icon="cubes" href="/cn/graphql/schema/cubes">
    浏览全部 25 个 Cube——字段、selector 与数仓分层。
  </Card>

  <Card title="Chain Group" icon="layer-group" href="/cn/graphql/schema/chain-groups">
    了解 EVM、Solana、Trading 三个 Chain Group 及其可用 Cube。
  </Card>

  <Card title="Dataset 与 Aggregates" icon="database" href="/cn/graphql/schema/dataset-aggregates">
    使用 `dataset` 与 `aggregates` 控制数据源范围与预聚合行为。
  </Card>

  <Card title="筛选" icon="filter" href="/cn/graphql/schema/filtering">
    学习如何用 `where` 与 selector 快捷方式收窄查询。
  </Card>

  <Card title="排序与分页" icon="arrow-down-1-9" href="/cn/graphql/schema/ordering-pagination">
    使用 `orderBy` 与 `limit` 对大数据集排序与分页。
  </Card>

  <Card title="指标与聚合" icon="chart-simple" href="/cn/graphql/schema/metrics-aggregation">
    在查询中使用 `count`、`sum`、`avg`、`min`、`max`、`uniq` 聚合数据。
  </Card>
</CardGroup>