> ## 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 Unit（CU）** を消費します。クレジットは REST API と同じ請求プランから差し引かれ、API Key は両方で共通です。

<Info>
  GraphQL API は REST Data API と同じ API Key・請求プランを共有します。GraphQL で消費したクレジットは全体の利用量に含まれます。
</Info>

***

## クレジット計算式

クレジットは Cube ごとに **5 要因の式** で計算されます。最終的な 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` など）を 1 つ追加するごとにコストが約 10% 増。    |
| **ComplexityFactor**  | `min(1.0 + min(select_count, 250) / 50 × 0.2, 1.5)` | 選択フィールドが増えるとコスト増（最大 1.5 倍）。フィールド約 5 個の単純クエリでは要因は約 1.02。 |

<Note>
  **0 行のクエリは無料です。** 他の要因に関わらず、結果が 0 行ならクレジットは課金されません。
</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`）に含まれます。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` を小さく保ちます。100 行ごとに LimitFactor が増えます。
  </Card>

  <Card title="事前集計 Cube を使う" icon="layer-group">
    集計データには、DWD の Cube（DEXTrades）でメトリクスを回すより、DWM/DWS の Cube（Pairs、Tokens、TokenHolders）を優先します。
  </Card>
</CardGroup>

***

## 関連ドキュメント

<CardGroup cols={2}>
  <Card title="課金とユニット（概要）" icon="receipt" href="/jp/docs/platform/billing-payments/plans-and-units">
    ChainStream の請求プラン、ユニット枠、支払い方法の概要。
  </Card>

  <Card title="メトリクスと集計" icon="chart-simple" href="/jp/graphql/schema/metrics-aggregation">
    集計メトリクスがクエリのクレジットに与える影響。
  </Card>
</CardGroup>