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

# 스키마 개요

> ChainStream GraphQL 스키마의 구조 — Chain Groups, Cube 필드, 생성 타입, 인트로스펙션

## 동적 스키마 생성

ChainStream GraphQL 스키마는 시작 시 **activecube-rs** 가 **Cube** 정의를 컴파일해 완전히 타입이 지정된 [async-graphql](https://github.com/async-graphql/async-graphql) 스키마로 **동적 생성**합니다. 각 Cube는 OLAP 테이블에 대응하는 분석 데이터 모델이며, activecube-rs가 자동으로 다음을 만듭니다:

* Cube용 **최상위 Query 필드**(해당 Chain Group 아래에 중첩)
* 선택 가능한 차원을 나타내는 **Record 타입**(`{Cube}Record`)
* 차원 계층과 맞는 **Filter 입력**(`{Cube}Filter`)
* 모든 차원 경로에 대한 ASC/DESC 변형을 가진 **OrderBy enum**(`{Cube}OrderBy`)

즉 스키마는 기저 데이터 모델과 항상 맞고, SDL 파일을 수동으로 유지할 필요가 없습니다.

<Info>
  스키마가 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 캔들, 토큰 통계), 데이터에 `chain` 차원 |

<Note>
  **EVM** 그룹은 어떤 체인을 조회할지 선택하려면 `network` 인자가 필요합니다. **Solana** 와 **Trading** 은 `network` 인자가 필요 없습니다 — Solana는 암시적이고, Trading은 데이터 안에 `chain` 차원이 있습니다.
</Note>

각 그룹에 어떤 Cube가 속하는지 자세한 내용은 [Chain Groups](/ko/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](/ko/graphql/schema/dataset-aggregates) 를 참고하세요.
</Tip>

***

## 공통 인자 패턴

Chain Group 안에서 모든 Cube 필드는 동일한 표준 인자 집합과, 선택적인 Cube별 **selector** 를 받습니다:

| 인자          | 타입              | 필수  | 설명                                    |
| :---------- | :-------------- | :-- | :------------------------------------ |
| `where`     | `{Cube}Filter`  | 아니오 | 차원 계층과 맞는 중첩 필터 객체                    |
| `limit`     | `LimitInput`    | 아니오 | 페이지네이션: `{count: Int, offset: Int}`   |
| `orderBy`   | `{Cube}OrderBy` | 아니오 | 정렬 enum(`{Path}_ASC` / `{Path}_DESC`) |
| *selectors* | Filter 입력       | 아니오 | 단축 필터(예: `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 enum" icon="arrow-down-a-z">
    `{Cube}OrderBy` — 모든 차원 경로에 대한 ASC/DESC enum 변형(예: `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

스키마는 표준 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 스키마를 자동으로 가져와 자동완성과 인라인 문서를 제공합니다. introspection 쿼리를 직접 쓰지 않고도 전체 스키마를 대화형으로 탐색할 수 있습니다.
</Tip>

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="데이터 Cube" icon="cubes" href="/ko/graphql/schema/cubes">
    25개 Cube의 필드, selector, 데이터 웨어하우스 레이어를 살펴봅니다.
  </Card>

  <Card title="Chain Groups" icon="layer-group" href="/ko/graphql/schema/chain-groups">
    EVM, Solana, Trading Chain Group과 사용 가능한 Cube를 이해합니다.
  </Card>

  <Card title="Dataset & Aggregates" icon="database" href="/ko/graphql/schema/dataset-aggregates">
    `dataset` 과 `aggregates` 로 데이터 범위와 사전 집계 동작을 제어합니다.
  </Card>

  <Card title="필터링" icon="filter" href="/ko/graphql/schema/filtering">
    `where` 필터와 selector 단축으로 쿼리를 좁히는 방법을 익힙니다.
  </Card>

  <Card title="정렬 및 페이지네이션" icon="arrow-down-1-9" href="/ko/graphql/schema/ordering-pagination">
    `orderBy` 와 `limit` 으로 결과를 정렬하고 큰 데이터셋을 페이지 넘깁니다.
  </Card>

  <Card title="메트릭 및 집계" icon="chart-simple" href="/ko/graphql/schema/metrics-aggregation">
    쿼리에서 `count`, `sum`, `avg`, `min`, `max`, `uniq` 로 데이터를 집계합니다.
  </Card>
</CardGroup>