> ## 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 Overview

> How the ChainStream GraphQL schema is structured — Chain Groups, Cube fields, generated types, and introspection

## Dynamic Schema Generation

The ChainStream GraphQL schema is **dynamically generated** at startup by **activecube-rs**, a Rust library that compiles **Cube** definitions into a fully-typed [async-graphql](https://github.com/async-graphql/async-graphql) schema. Each Cube maps to an analytical data model backed by an OLAP table, and activecube-rs automatically produces:

* A **top-level Query field** for the Cube (nested under its Chain Group)
* A **Record type** (`{Cube}Record`) representing the selectable dimensions
* A **Filter input** (`{Cube}Filter`) matching the dimension hierarchy
* An **OrderBy enum** (`{Cube}OrderBy`) with ASC/DESC variants for every dimension path

This means the schema is always in sync with the underlying data models — no handwritten SDL files to maintain.

<Info>
  Because the schema is generated from Cube definitions, any new data model added in Rust is automatically reflected in the GraphQL endpoint after deployment.
</Info>

***

## Root Query Structure

The root query type is named `ChainStream`. Cubes are organized into three **Chain Groups**, each exposed as a top-level field:

```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!]!
  }
}
```

There are no `Mutation` or `Subscription` types — the GraphQL API is read-only analytical queries.

***

## Chain Groups

Cubes are organized into three groups based on the blockchain ecosystem they target:

| Chain Group | `network` Argument | Available Networks                | Description                                                                                |
| :---------- | :----------------- | :-------------------------------- | :----------------------------------------------------------------------------------------- |
| **EVM**     | Required           | `eth`, `bsc`, `polygon`           | Shared Cubes for all EVM-compatible chains                                                 |
| **Solana**  | Not needed         | `sol` (implicit)                  | Cubes for Solana including chain-specific ones (Instructions, DEXOrders)                   |
| **Trading** | Not needed         | Cross-chain (`sol`, `eth`, `bsc`) | Pre-aggregated trading analytics (OHLC candles, token statistics) with a `chain` dimension |

<Note>
  The **EVM** group requires a `network` argument to select which chain to query. **Solana** and **Trading** do not need a `network` argument — Solana is implicit, and Trading includes a `chain` dimension within the data.
</Note>

See [Chain Groups](/en/graphql/schema/chain-groups) for the full breakdown of which Cubes belong to each group.

***

## Chain Group Parameters

Every Chain Group accepts two optional parameters that control data source behavior:

### Dataset

The `dataset` parameter controls the time scope of data queried:

| Value      | Description                                                        |
| :--------- | :----------------------------------------------------------------- |
| `combined` | Full range — queries both recent and historical data **(default)** |
| `realtime` | Recent data only (approximately the last 24 hours)                 |
| `archive`  | Historical data up to the retention TTL                            |

```graphql theme={null}
query {
  Solana(dataset: realtime) {
    DEXTrades(limit: {count: 10}, orderBy: {descending: Block_Time}) {
      Block { Time }
      Trade { Buy { Amount } }
    }
  }
}
```

### Aggregates

The `aggregates` parameter controls whether pre-aggregated (DWM/DWS) tables are used:

| Value  | Description                                                                    |
| :----- | :----------------------------------------------------------------------------- |
| `yes`  | Prefer pre-aggregated tables when available **(default for applicable Cubes)** |
| `no`   | Use raw detail tables only                                                     |
| `only` | Only use pre-aggregated tables (faster but limited fields)                     |

```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>
  See [Dataset & Aggregates](/en/graphql/schema/dataset-aggregates) for detailed usage, supported tables, and performance guidance.
</Tip>

***

## Common Argument Pattern

Within a Chain Group, every Cube field accepts the same set of standard arguments, plus optional Cube-specific **selectors**:

| Argument    | Type            | Required | Description                                           |
| :---------- | :-------------- | :------- | :---------------------------------------------------- |
| `where`     | `{Cube}Filter`  | No       | Nested filter object matching the dimension hierarchy |
| `limit`     | `LimitInput`    | No       | Pagination: `{count: Int, offset: Int}`               |
| `orderBy`   | `{Cube}OrderBy` | No       | Sort order enum (`{Path}_ASC` / `{Path}_DESC`)        |
| *selectors* | Filter input    | No       | Shortcut filters (e.g., `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)
}
```

Default `count` varies by Cube (typically 25). Maximum is 10,000 for most Cubes.

***

## Generated Types per Cube

For each Cube, activecube-rs generates three companion types:

<CardGroup cols={3}>
  <Card title="Record Type" icon="table">
    `{Cube}Record` — The return type containing all selectable dimensions and metrics. Field structure mirrors the Cube's dimension hierarchy.
  </Card>

  <Card title="Filter Input" icon="filter">
    `{Cube}Filter` — A nested input object where each dimension maps to a filter primitive (`StringFilter`, `IntFilter`, `DateTimeFilter`, etc.).
  </Card>

  <Card title="OrderBy Enum" icon="arrow-down-a-z">
    `{Cube}OrderBy` — Enum variants for every dimension path in both ASC and DESC directions (e.g., `Block_Time_ASC`, `Trade_Buy_Amount_DESC`).
  </Card>
</CardGroup>

**Example for 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

The schema supports standard GraphQL introspection. You can explore types, fields, and arguments using `__schema` and `__type` queries:

<Tabs>
  <Tab title="List All Cubes">
    ```graphql theme={null}
    query {
      __schema {
        queryType {
          fields {
            name
            description
            args { name type { name } }
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Inspect a Cube Type">
    ```graphql theme={null}
    query {
      __type(name: "DEXTradesRecord") {
        name
        fields {
          name
          type { name kind ofType { name } }
        }
      }
    }
    ```
  </Tab>

  <Tab title="List Filter Operators">
    ```graphql theme={null}
    query {
      __type(name: "StringFilter") {
        name
        inputFields {
          name
          type { name kind }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  The [GraphQL IDE](https://ide.chainstream.io) auto-fetches the introspection schema to power auto-complete and inline documentation. You can explore the full schema interactively without writing introspection queries manually.
</Tip>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Data Cubes" icon="cubes" href="/en/graphql/schema/cubes">
    Explore all 25 Cubes — their fields, selectors, and data warehouse layers.
  </Card>

  <Card title="Chain Groups" icon="layer-group" href="/en/graphql/schema/chain-groups">
    Understand the EVM, Solana, and Trading Chain Groups and their available Cubes.
  </Card>

  <Card title="Dataset & Aggregates" icon="database" href="/en/graphql/schema/dataset-aggregates">
    Control data source scope and pre-aggregation behavior with `dataset` and `aggregates`.
  </Card>

  <Card title="Filtering" icon="filter" href="/en/graphql/schema/filtering">
    Learn how to use `where` filters and selector shortcuts to narrow your queries.
  </Card>

  <Card title="Ordering & Pagination" icon="arrow-down-1-9" href="/en/graphql/schema/ordering-pagination">
    Sort results and paginate through large datasets with `orderBy` and `limit`.
  </Card>

  <Card title="Metrics & Aggregation" icon="chart-simple" href="/en/graphql/schema/metrics-aggregation">
    Use `count`, `sum`, `avg`, `min`, `max`, and `uniq` to aggregate data in your queries.
  </Card>
</CardGroup>