스키마 개요

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

​

동적 스키마 생성

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

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

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

스키마가 Cube 정의에서 생성되므로 Rust에 새 데이터 모델이 추가되면 배포 후 GraphQL 엔드포인트에 자동으로 반영됩니다.

---

​

루트 쿼리 구조

루트 쿼리 타입 이름은 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!]!
    # ... 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 차원

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

각 그룹에 어떤 Cube가 속하는지 자세한 내용은 Chain Groups 를 참고하세요.

---

​

Chain Group 파라미터

모든 Chain Group은 데이터 소스 동작을 제어하는 선택 파라미터 두 가지를 받습니다:

​

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별 selector 를 받습니다:

인자	타입	필수	설명
where	{Cube}Filter	아니오	차원 계층과 맞는 중첩 필터 객체
limit	LimitInput	아니오	페이지네이션: {count: Int, offset: Int}
orderBy	{Cube}OrderBy	아니오	정렬 enum({Path}_ASC / {Path}_DESC)
selectors	Filter 입력	아니오	단축 필터(예: 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가 세 가지 동반 타입을 생성합니다:

Record 타입

{Cube}Record — 선택 가능한 모든 차원과 메트릭을 담는 반환 타입. 필드 구조는 Cube의 차원 계층을 따릅니다.

Filter 입력

{Cube}Filter — 각 차원이 필터 프리미티브(StringFilter, IntFilter, DateTimeFilter 등)에 매핑되는 중첩 입력 객체.

OrderBy enum

{Cube}OrderBy — 모든 차원 경로에 대한 ASC/DESC enum 변형(예: 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

스키마는 표준 GraphQL introspection을 지원합니다. __schema 와 __type 쿼리로 타입·필드·인자를 탐색할 수 있습니다:

모든 Cube 나열

query {
  __schema {
    queryType {
      fields {
        name
        description
        args { name type { name } }
      }
    }
  }
}

Cube 타입 조사

query {
  __type(name: "DEXTradesRecord") {
    name
    fields {
      name
      type { name kind ofType { name } }
    }
  }
}

필터 연산자 나열

query {
  __type(name: "StringFilter") {
    name
    inputFields {
      name
      type { name kind }
    }
  }
}

GraphQL IDE 가 introspection 스키마를 자동으로 가져와 자동완성과 인라인 문서를 제공합니다. introspection 쿼리를 직접 쓰지 않고도 전체 스키마를 대화형으로 탐색할 수 있습니다.

---

​

다음 단계

데이터 Cube

25개 Cube의 필드, selector, 데이터 웨어하우스 레이어를 살펴봅니다.

Chain Groups

EVM, Solana, Trading Chain Group과 사용 가능한 Cube를 이해합니다.

Dataset & Aggregates

dataset 과 aggregates 로 데이터 범위와 사전 집계 동작을 제어합니다.

필터링

where 필터와 selector 단축으로 쿼리를 좁히는 방법을 익힙니다.

정렬 및 페이지네이션

orderBy 와 limit 으로 결과를 정렬하고 큰 데이터셋을 페이지 넘깁니다.

메트릭 및 집계

쿼리에서 count, sum, avg, min, max, uniq 로 데이터를 집계합니다.