计费与额度

了解 GraphQL API 查询如何通过 Credit Unit 系统计费

​

概述

每条 GraphQL 查询会消耗根据查询复杂度动态计算的 Credit Units（CU，信用单位）。额度与 REST Data API 共用同一计费计划 —— 同一 API Key 即可访问两者。

GraphQL API 与 REST Data API 共用 API Key 与计费计划。GraphQL 查询消耗的额度计入总用量。

---

​

额度计算公式

按 Cube 采用 五因子公式 计算额度。最终 CU 取决于查询内容、请求行数、是否聚合、指标数量以及选中字段数。

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

因子	计算方式	说明
BaseCost	各 Cube 内部基准值	反映底层表规模与扫描成本，不同 Cube 不同。
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。

零行查询不扣费。 若查询无返回行，无论其他因子如何均不计费。

​

计算示例

简单查询：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 + 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）。零行返回的查询不计费。

---

​

在 IDE 中监控用量

GraphQL IDE 状态栏会在每次查询后显示额度消耗：

• CU 指示：显示本次消耗的总 CU
• 延迟：请求耗时（毫秒）
• 响应大小：载荷体积

---

​

优化额度使用的建议

少选字段

只请求需要的维度。ComplexityFactor 随选中字段数增加。

合理 limit

在可接受范围内尽量降低 limit.count。LimitFactor 每多 100 行约翻倍。

优先预聚合 Cube

需要汇总数据时，优先使用 DWM/DWS Cube（Pairs、Tokens、TokenHolders），而非在 DWD Cube（DEXTrades）上跑指标。

---

​

相关文档

计费与单位（总览）

ChainStream 计费计划、额度配额与支付方式概览。

指标与聚合

了解聚合指标如何影响查询额度。