빌링 및 크레딧

GraphQL API 쿼리가 Credit Unit 시스템으로 어떻게 과금되는지 이해

​

개요

모든 GraphQL 쿼리는 쿼리 복잡도에 따라 동적으로 계산되는 **Credit Unit(CU)**을 소비합니다. 크레딧은 REST API와 동일한 과금 플랜에서 차감되며, API Key 하나로 둘 다 사용할 수 있습니다.

GraphQL API는 REST Data API와 동일한 API Key·과금 플랜을 공유합니다. GraphQL 쿼리로 소비한 크레딧은 전체 사용량에 포함됩니다.

---

​

크레딧 계산 공식

크레딧은 Cube마다 5요인 공식으로 계산됩니다. 최종 CU는 조회 내용, 요청 행 수, 집계 사용 여부, 포함한 metric 수, 선택한 필드 수에 따라 달라집니다.

CU = ceil(BaseCost × LimitFactor × AggregationFactor × MetricFactor × ComplexityFactor) / 100

요인	계산	설명
BaseCost	Cube별 내부 값	기본 테이블 크기·스캔 비용을 반영합니다. Cube마다 base cost가 다릅니다.
LimitFactor	ceil(limit / 100), 최소 1	요청 행 수에 선형으로 비례합니다. 1–100행은 동일 비용, 101–200은 2배 등입니다.
AggregationFactor	1.0(없음), 1.5(GROUP BY), 2.0(HAVING)	집계 또는 사후 집계 필터(selectWhere) 사용 시 더 큽니다.
MetricFactor	1.0 + (aggregate_count × 0.1)	집계 함수(count, sum, avg 등)마다 비용에 10%가 가산됩니다.
ComplexityFactor	min(1.0 + min(select_count, 250) / 50 × 0.2, 1.5)	선택 필드가 많을수록 비용이 증가하며 최대 1.5배로 캡됩니다. 필드 약 5개인 단순 쿼리는 요인이 약 1.02입니다.

0행 쿼리는 무료입니다. 결과 행이 없으면 다른 요인과 관계없이 크레딧이 청구되지 않습니다.

​

계산 예시

단순 쿼리: 10행, 5필드

BaseCost = 2000 (internal), LimitFactor = ceil(10/100) = 1
AggregationFactor = 1.0, MetricFactor = 1.0
ComplexityFactor = 1.0 + (5/50) × 0.2 = 1.02
Internal = ceil(2000 × 1 × 1.0 × 1.0 × 1.02) = 2040
CU = 2040 / 100 = 20.40 CU

대용량 쿼리: 500행, 5필드

BaseCost = 2000, LimitFactor = ceil(500/100) = 5
AggregationFactor = 1.0, MetricFactor = 1.0
ComplexityFactor = 1.02
Internal = ceil(2000 × 5 × 1.0 × 1.0 × 1.02) = 10200
CU = 10200 / 100 = 102.00 CU

집계 쿼리: GROUP BY + metric 2개, 500행

BaseCost = 2000, LimitFactor = ceil(500/100) = 5
AggregationFactor = 1.5 (GROUP BY)
MetricFactor = 1.0 + 2 × 0.1 = 1.2
ComplexityFactor = 1.02
Internal = ceil(2000 × 5 × 1.5 × 1.2 × 1.02) = 18360
CU = 18360 / 100 = 183.60 CU

복잡 쿼리: 많은 필드 선택

BaseCost = 2000, LimitFactor = 1
AggregationFactor = 1.0, MetricFactor = 1.0
ComplexityFactor = min(1.0 + (250/50) × 0.2, 1.5) = 1.5 (capped)
Internal = ceil(2000 × 1 × 1.0 × 1.0 × 1.5) = 3000
CU = 3000 / 100 = 30.00 CU

CU는 동적으로 계산되므로, 정확한 비용을 알려면 응답의 extensions.credits 필드를 확인하거나 IDE 상태 표시줄의 CU 표시를 보는 것이 가장 좋습니다.

---

​

응답: extensions.credits

모든 GraphQL 응답의 extensions에 크레딧 소비 정보가 포함됩니다.

{
  "data": {
    "Solana": {
      "DEXTrades": [ ... ]
    }
  },
  "extensions": {
    "credits": {
      "total": 20.4,
      "unit": "CU",
      "cubes": [
        {
          "cube": "DEXTrades",
          "credits": 20.4,
          "row_count": 10
        }
      ]
    }
  }
}

필드	타입	설명
total	Float	전체 쿼리에서 소비한 총 CU
unit	String	항상 "CU"
cubes	Array	Cube별 내역
cubes[].cube	String	과금 엔진에서 쓰는 Cube 이름
cubes[].credits	Float	해당 Cube에 청구된 CU
cubes[].row_count	Int	반환된 행 수

extensions.credits는 크레딧이 소비될 때(total > 0) 포함됩니다. 0행을 반환하는 쿼리는 청구되지 않습니다.

---

​

IDE에서 사용량 모니터링

GraphQL IDE 상태 표시줄에 각 쿼리 후 크레딧 소비가 표시됩니다.

• CU 표시: 소비한 총 CU
• 지연 시간: 요청 소요 시간(ms)
• 응답 크기: 페이로드 크기

---

​

크레딧 사용 최적화 팁

필드는 적게

필요한 dimension만 요청하세요. ComplexityFactor는 선택 필드 수에 따라 증가합니다.

limit는 적절히

실용적인 범위에서 limit.count를 낮게 유지하세요. LimitFactor는 행이 100개 늘어날 때마다 배가됩니다.

사전 집계 Cube 활용

집계 데이터는 DWD Cube(DEXTrades)에 metric을 돌리기보다 DWM/DWS Cube(Pairs, Tokens, TokenHolders)를 우선하세요.

---

​

관련 문서

결제 및 단위(일반)

ChainStream 과금 플랜, 단위 할당, 결제 수단 개요.

메트릭 및 집계

집계 metric이 쿼리 크레딧에 미치는 영향.