> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickHouse における Prometheus HTTP API のサポート: TimeSeries テーブルを介したリモート書き込み、リモート読み取り、PromQL クエリ。

# Prometheus HTTP API と PromQL

export const PrivatePreviewBadge = () => {
  return <div className="privatePreviewBadge">
            <div className="privatePreviewIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M5.33301 6.66667V4.66667V4.66667C5.33301 3.194 6.52701 2 7.99967 2V2C9.47234 2 10.6663 3.194 10.6663 4.66667V4.66667V6.66667" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path d="M8.00033 9.33337V11.3334" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path fillRule="evenodd" clipRule="evenodd" d="M11.333 14H4.66634C3.92967 14 3.33301 13.4033 3.33301 12.6666V7.99996C3.33301 7.26329 3.92967 6.66663 4.66634 6.66663H11.333C12.0697 6.66663 12.6663 7.26329 12.6663 7.99996V12.6666C12.6663 13.4033 12.0697 14 11.333 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'プライベートプレビュー'}
        </div>;
};

<PrivatePreviewBadge />

ClickHouse は [`TimeSeries`](/ja/reference/engines/table-engines/integrations/time-series) テーブルを介して Prometheus HTTP API を実装しています。単一のハンドラーが、リモート書き込み、リモート読み取り、インスタント PromQL クエリ、範囲 PromQL クエリを処理します。

Prometheus サーバーがスクレイプできるように ClickHouse 自身のメトリクスを公開する方法については、[Prometheus メトリクスエンドポイント](/ja/concepts/features/interfaces/prometheus-metrics)を参照してください。

<h2 id="prerequisites">
  前提条件
</h2>

セットアップ手順は ClickHouse Cloud とセルフマネージドの ClickHouse で異なります。ご利用のデプロイメントに該当するセクションに従ってください。

<h3 id="prerequisites-cloud">
  ClickHouse Cloud
</h3>

<Note>
  ClickHouse Cloud における PromQL のサポートはプライベートプレビューです。プライベートプレビューの対象となっているサービスでは、`enable_time_series_table` 設定と Prometheus API エンドポイントがすでに構成済みです。それ以外の ClickHouse Cloud サービスにはこの構成がなく、ユーザー自身でこの機能を有効化することはできません。以降のセクションで説明する `SET enable_time_series_table` ステートメントおよび `http_handlers` の構成は、セルフマネージドのデプロイメントに適用されるものです。
</Note>

プライベートプレビューの対象となっているサービスでは、[TimeSeries テーブルを作成する](#create-a-timeseries-table)に進んでください。対象サービスでは、[エンドポイント一覧](#configure-prometheus-api)に記載されたエンドポイントパスが利用できます。

<h3 id="enable-the-timeseries-setting">
  セルフマネージド: TimeSeries設定を有効にする
</h3>

テーブルを作成しアクセスするユーザーに対して、`enable_time_series_table` 設定を有効にします。

```sql theme={null}
SET enable_time_series_table = 1;
```

HTTP APIリクエストの場合は、APIユーザーのプロファイルで`enable_time_series_table`を有効にします。

<h3 id="configure-prometheus-api">
  セルフマネージド: Prometheus API エンドポイントを設定する
</h3>

ClickHouse のメイン HTTP ポートで、プレフィックスルーティングされたハンドラーを 1 つ設定します。

```xml theme={null}
<http_handlers>
    <defaults/>
    <rule>
        <url_prefix>/prometheus/api/v1</url_prefix>
        <handler>
            <type>prometheus_api_v1</type>
        </handler>
    </rule>
</http_handlers>
```

`<defaults/>` は、`/ping` などのエンドポイントや SQL リクエスト用の組み込みハンドラーを維持します。上記のプレフィックスにより、これらのエンドポイントを 1 つのハンドラー経由で公開します。

| エンドポイント | 用途 |
| - | - |
| `/prometheus/api/v1/write` | Prometheus リモート書き込み |
| `/prometheus/api/v1/read` | Prometheus リモート読み取り |
| `/prometheus/api/v1/query` | インスタント PromQL クエリ |
| `/prometheus/api/v1/query_range` | 範囲 PromQL クエリ |
| `/prometheus/api/v1/format_query` | PromQL 式のフォーマット |
| `/prometheus/api/v1/series` | シリーズのメタデータ |
| `/prometheus/api/v1/metadata` | メトリクスファミリーのメタデータ |

この例では、ハンドラーに `database` と `table` を指定していません。各リクエストで `table` クエリパラメータを指定する必要があります (`/format_query` は指定された PromQL 式をパースするだけなので、テーブルは不要です) 。また、`database` を指定する、`prometheus.metrics` のような完全修飾テーブル名を使用する、またはデータベースを省略して `default` を使用することもできます。これにより、1 つのハンドラーで複数の `TimeSeries` テーブルを処理できます。

すべてのリクエストで 1 つの固定テーブルを使用するには、ハンドラーで設定します。

```xml theme={null}
<handler>
    <type>prometheus_api_v1</type>
    <database>prometheus</database>
    <table>metrics</table>
</handler>
```

ハンドラーで設定されたテーブルは、リクエストパラメータで上書きできません。

ルーティングとハンドラーの設定:

| 名前 | デフォルト | 説明 |
| - | - | - |
| `url_prefix` | none | 設定されたプレフィックスで始まるすべてのリクエストパスに一致するルールフィルター。 |
| `table` | none | `TimeSeries` テーブル名。省略した場合、リクエストで `table` クエリパラメータを指定する必要があります。設定する名前にはデータベースを含めることができます。 |
| `database` | none | テーブルを含むデータベース。リクエストでクエリパラメータとして指定できます。省略した場合、ClickHouse は完全修飾された `table` 値に含まれるデータベースを使用し、指定がなければ `default` を使用します。 |

<h3 id="create-a-timeseries-table">
  TimeSeriesテーブルを作成する
</h3>

データベースと `TimeSeries` テーブルを作成します。

```sql theme={null}
CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;
```

<h2 id="remote-write">
  リモート書き込み を使用してメトリクスを取り込む
</h2>

ClickHouse は [Prometheus リモート書き込み プロトコル](https://prometheus.io/docs/specs/remote_write_spec/)をサポートしています。Prometheus がハンドラーに書き込むように設定します。

```yaml theme={null}
remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>
```

Prometheus はサンプルを `prometheus.metrics` テーブルに送信します。

多数の同時実行 リモート書き込み リクエストからのデータを少ないパーツにまとめるには、URL に `async_insert` 設定を追加する (またはユーザープロファイルで有効にする) ことで、[非同期挿入](/ja/reference/settings/session-settings/async-insert#async_insert)を有効にします。

```yaml theme={null}
remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics&async_insert=1
```

ClickHouse は、[`wait_for_async_insert`](/ja/reference/settings/session-settings/wait-for#wait_for_async_insert) 設定にかかわらず、データが `TimeSeries` テーブルのすべての内部テーブルにフラッシュされた後にのみ、非同期 リモート書き込み リクエストを受理します。リモート書き込み プロトコルでは、受理された書き込みは永続化済みとして扱われます。フラッシュに失敗した場合、リクエストはエラーを返し、Prometheus は再試行します。

<h2 id="promql-query-support">
  PromQL でクエリを実行する
</h2>

instant-query エンドポイントを使用して、特定の時点における PromQL 式を評価します。

```bash theme={null}
curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"
```

range-query エンドポイントを使用して、指定した時間範囲で式を評価します。

```bash theme={null}
curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query_range" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "start=2026-08-15T12:00:00Z" \
  --data-urlencode "end=2026-08-15T13:00:00Z" \
  --data-urlencode "step=60s" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"
```

クエリエンドポイントは、フォームボディでのパラメータ受け渡しにも対応しています。`--get` を指定しない場合、curl はパラメータを `application/x-www-form-urlencoded` として `POST` で送信します。

```bash theme={null}
curl --user default:<password> \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query_range" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "start=2026-08-15T12:00:00Z" \
  --data-urlencode "end=2026-08-15T13:00:00Z" \
  --data-urlencode "step=60s" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"
```

フォーマット-query エンドポイントを使用して、PromQL 式を評価せずにパースおよびフォーマットします。

```bash theme={null}
curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/format_query" \
  --data-urlencode "query=sum by(job)(http_requests_total{code=\"200\"})/2"
```

式はパース済みクエリからシリアライズされて返され、空白は正規化され、コメントは削除され、冗長な括弧は除去され、期間は秒数に変換されます: `sum by (job) (http_requests_total{code="200"}) / 2`。このエンドポイントは式を評価しないため、`database` および `table` パラメータは不要です。

HTTP API、`promql` 方言、およびテーブル関数で使用される関数と集約演算子の一覧については、[サポートされている PromQL 機能](/ja/reference/functions/table-functions/prometheusQueryRange#supported-promql-features)を参照してください。

<h3 id="grafana">
  Grafana
</h3>

ベース URL が `/api/v1` の直前までとなるように、Prometheus データソースを設定します。

```yaml theme={null}
apiVersion: 1
datasources:
  - name: ClickHouse Prometheus
    type: prometheus
    access: proxy
    url: https://clickhouse.example.com:8443/prometheus
    basicAuth: true
    basicAuthUser: default
    jsonData:
      httpMethod: POST
      customQueryParameters: database=prometheus&table=metrics
    secureJsonData:
      basicAuthPassword: <password>
```

Grafana は、このベース URL に `/api/v1/query` または `/api/v1/query_range` を付加し、各リクエストに `customQueryParameters` を追加します。

`httpMethod: POST` の場合、Grafana はクエリパラメータをリクエストボディで送信します。ClickHouse はリクエストボディと URL のクエリ文字列の両方を読み取るため、`customQueryParameters` は引き続き適用されます。URL には長さの制限があるため、長い PromQL 式には `POST` を使用してください。

<Note>
  実装されているのは、クエリエンドポイント `/api/v1/query`、`/api/v1/query_range`、`/api/v1/format_query`、およびメタデータエンドポイント `/api/v1/series`、`/api/v1/labels`、`/api/v1/label/<name>/values`、`/api/v1/metadata` のみです。`/api/v1/series` には少なくとも 1 つの `match[]` シリーズセレクターが必要で、任意の `start`、`end`、`limit` パラメータをサポートし、各セレクターに一致するシリーズのユニオンを返します。`/api/v1/labels` は同じパラメータを受け付けますが、`match[]` は任意であり、一致するシリーズのソート済みラベル名を返します (セレクターが指定されていない場合はすべてのシリーズのラベル名を返します) 。`/api/v1/label/<name>/values` は `/api/v1/labels` と同じパラメータを受け付け、1 つのラベルのソート済みの値を返します。`<name>` には、`[a-zA-Z0-9_]` 以外の文字を含むラベル名に対して Prometheus の `U__...` エスケープを任意で使用できます。これらのエンドポイントは、Grafana の Prometheus データソースがラベルの参照、Template 変数、クエリビルダーでの自動補完に使用する機能をカバーします。
</Note>

<h3 id="sql-entry-points">
  SQL エントリポイント
</h3>

ClickHouse では、HTTP API、`promql` 方言、および [`prometheusQuery`](/ja/reference/functions/table-functions/prometheusQuery) と [`prometheusQueryRange`](/ja/reference/functions/table-functions/prometheusQueryRange) のテーブル関数で、同じ PromQL コンバーターを使用します。

`clickhouse-client` で PromQL を直接実行します。

```bash theme={null}
clickhouse-client \
  --dialect promql \
  --promql_database prometheus \
  --promql_table metrics \
  --query 'rate(http_requests_total[5m])'
```

テーブル関数を使用して、SQLクエリ内にPromQLを埋め込みます。

```sql theme={null}
SELECT *
FROM prometheusQuery(
    prometheus.metrics,
    'rate(http_requests_total[5m])',
    now()
);
```

<h2 id="metadata">
  メトリクスのメタデータをクエリする
</h2>

`/prometheus/api/v1/metadata` エンドポイントは、`TimeSeries` テーブルの `Metrics` ターゲットテーブルに格納されているメトリクスのメタデータ (各メトリクスファミリーの型、ヘルプテキスト、単位) を返します。URL のクエリ文字列では、次の Prometheus パラメータをサポートしています。

| パラメータ | 説明 |
| - | - |
| `metric` | 指定したメトリクスファミリーのメタデータのみを返します。 |
| `limit` | 返されるメトリクスファミリーの数を制限します。負の値は無制限を意味し、ゼロの場合はメトリクスファミリーを返しません。 |
| `limit_per_metric` | 各メトリクスファミリーについて返されるメタデータオブジェクトの数を制限します。ゼロおよび負の値は無制限を意味します。 |

デフォルトの `Metrics` ターゲットテーブルは、メトリクスファミリー名で順序付けられた `ReplacingMergeTree` です。各メトリクスファミリーについて、最後に書き込まれたメタデータエントリを保持します。ファミリーごとに複数のエントリが返されるのは、ターゲットテーブルにそれらが保持されている場合のみです。つまり、パーツがマージされる前、またはそれらを保持するエンジンでテーブルが定義されている場合です。

```bash theme={null}
curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/metadata" \
  --data-urlencode "metric=http_requests_total" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"
```

<h2 id="remote-read">
  リモート読み取り でメトリクスを読み取る
</h2>

ClickHouse は、`/prometheus/api/v1/read` で [Prometheus リモート読み取り プロトコル](https://prometheus.io/docs/prometheus/latest/querying/remote_read_api/)をサポートしています。

同じ `TimeSeries` テーブルから読み取るように Prometheus サーバーを設定します。

```yaml theme={null}
remote_read:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>
```