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

# 计费与额度

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

## 概述

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

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

***

## 额度计算公式

按 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。   |

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

### 计算示例

<AccordionGroup>
  <Accordion title="简单查询：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
    ```
  </Accordion>

  <Accordion title="较大查询：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
    ```
  </Accordion>

  <Accordion title="聚合查询：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
    ```
  </Accordion>

  <Accordion title="复杂查询：选中大量字段">
    ```
    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
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  由于 CU 为动态计算，最准确的方式是查看响应中的 `extensions.credits` 字段，或关注 IDE 状态栏中的 CU 指示。
</Tip>

***

## 响应：`extensions.credits`

每条 GraphQL 响应在 `extensions` 中包含额度消耗详情：

```json theme={null}
{
  "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`    | 返回行数           |

<Note>
  在产生扣费时会出现 `extensions.credits`（即 `total > 0`）。零行返回的查询不计费。
</Note>

***

## 在 IDE 中监控用量

[GraphQL IDE](https://ide.chainstream.io) 状态栏会在每次查询后显示额度消耗：

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

***

## 优化额度使用的建议

<CardGroup cols={3}>
  <Card title="少选字段" icon="minimize">
    只请求需要的维度。ComplexityFactor 随选中字段数增加。
  </Card>

  <Card title="合理 limit" icon="gauge">
    在可接受范围内尽量降低 `limit.count`。LimitFactor 每多 100 行约翻倍。
  </Card>

  <Card title="优先预聚合 Cube" icon="layer-group">
    需要汇总数据时，优先使用 DWM/DWS Cube（Pairs、Tokens、TokenHolders），而非在 DWD Cube（DEXTrades）上跑指标。
  </Card>
</CardGroup>

***

## 相关文档

<CardGroup cols={2}>
  <Card title="计费与单位（总览）" icon="receipt" href="/cn/docs/platform/billing-payments/plans-and-units">
    ChainStream 计费计划、额度配额与支付方式概览。
  </Card>

  <Card title="指标与聚合" icon="chart-simple" href="/cn/graphql/schema/metrics-aggregation">
    了解聚合指标如何影响查询额度。
  </Card>
</CardGroup>