メインコンテンツへスキップ

​
前提条件

この記事の例では、以下が必要です。
  • 稼働中の ClickHouse server インスタンス
  • curl がインストールされていること。Ubuntu または Debian では、sudo apt install curl を実行するか、インストール方法についてはこのドキュメントを参照してください。

​
概要

HTTPインターフェイスを使用すると、任意のプラットフォーム上で、任意のプログラミング言語から、REST API の形式で ClickHouse を利用できます。HTTPインターフェイスはネイティブインターフェイスより機能が制限されていますが、より幅広い言語をサポートしています。 デフォルトでは、clickhouse-server は次のポートで待ち受けます。
  • HTTP はポート 8123
  • HTTPS はポート 8443 (有効にした場合)
パラメータを指定せずに GET / リクエストを送信すると、文字列 “Ok.” とともに 200 のレスポンスコードが返されます。
“Ok.” は http_server_default_response で定義されているデフォルト値で、必要に応じて変更できます。 あわせて参照してください: HTTP response codes caveats。

​
Webユーザーインターフェイス

ClickHouse には Webユーザーインターフェイスが含まれており、次のアドレスからアクセスできます。
Web UI は、クエリ実行中の進行状況の表示、クエリのキャンセル、結果のストリーミングに対応しています。 また、クエリパイプラインのチャートやグラフを表示するための隠し機能も備えています。 クエリが正常に実行されるとダウンロードボタンが表示され、CSV、TSV、JSON、JSONLines、Parquet、Markdown、または ClickHouse がサポートする任意のカスタムフォーマットなど、さまざまなフォーマットでクエリ結果をダウンロードできます。このダウンロード機能では、クエリを再実行せずに結果を効率よく取得するためにクエリキャッシュを使用します。UI に多数あるページのうち 1 ページしか表示されていない場合でも、完全な結果セットがダウンロードされます。 Web UI は、プロフェッショナルユーザー向けに設計されています。 ヘルスチェック用スクリプトでは GET /ping リクエストを使用してください。このハンドラーは常に “Ok.” を返します (末尾に改行付き) 。バージョン 18.12.13 以降で利用できます。レプリカの遅延を確認するには、関連項目として /replicas_status も参照してください。

​
HTTP/HTTPS 経由でのクエリ

HTTP/HTTPS 経由でクエリを実行する方法は 3 つあります。
  • リクエストを URL の ‘query’ パラメータとして送信する
  • POST メソッドを使用する
  • クエリの先頭を ‘query’ パラメータで送り、残りを POST で送信する
URL のサイズはデフォルトで 1 MiB に制限されています。これは http_max_uri_size 設定で変更できます。
成功した場合は、レスポンスコード 200 と結果がレスポンスボディで返されます。 エラーが発生した場合は、レスポンスコード 500 とエラーの説明テキストがレスポンスボディで返されます。 GET リクエストは ‘readonly’ です。つまり、データを変更するクエリでは POST メソッドしか使用できません。 クエリ自体は、POST ボディまたは URL パラメータのいずれかで送信できます。いくつか例を見てみましょう。 以下の例では、curl を使用してクエリ SELECT 1 を送信しています。スペースには URL エンコード %20 を使用している点に注意してください。
command
Response
この例では、-nv (非冗長) および -O- パラメータを指定した wget を使用し、結果をターミナルに出力します。 この場合、スペースを URL エンコードする必要はありません。
command
この例では、生のHTTPリクエストをパイプでnetcatに渡します：
command
response
ご覧のとおり、curl コマンドはやや扱いづらく、空白は URL エスケープする必要があります。 wget はすべて自動的にエスケープしてくれますが、keep-alive と Transfer-Encoding: chunked を使用する HTTP 1.1 では正常に動作しないため、使用は推奨していません。
クエリの一部をパラメータで送り、残りをPOSTで送ると、これら2つのデータ部分の間に改行が挿入されます。 たとえば、これは動作しません。
デフォルトでは、データは TabSeparated フォーマットで返されます。 別のフォーマットを指定するには、クエリで FORMAT 句を使用します。例:
command
Response
TabSeparated 以外のデフォルトフォーマットを指定するには、default_format URL パラメータまたは X-ClickHouse-Format ヘッダーを使用できます。
POSTメソッドでは、パラメータ化クエリを使用できます。パラメータは、{name:Type} のように、パラメータ名と型を中かっこで囲んで指定します。パラメータの値は param_name で渡します。

​
HTTP/HTTPS 経由の INSERT クエリ

INSERT クエリでは、データの送信に POST メソッドを使用する必要があります。この場合、クエリの先頭部分を URL パラメーターに記述し、挿入するデータは POST で渡せます。挿入するデータとしては、たとえば MySQL のタブ区切りの dump を使用できます。このように、INSERT クエリは MySQL の LOAD DATA LOCAL INFILE の代替として使用できます。

​
例

テーブルを作成するには：
データを挿入するには、使い慣れた INSERT クエリを使用します。
クエリとは別にデータを送信するには、
任意のデータフォーマットを指定できます。たとえば、INSERT INTO t VALUES の記述時に使用するものと同じ ‘Values’ フォーマットを指定できます:
タブ区切りのダンプからデータを挿入するには、適切なフォーマットを指定します。
テーブルの内容を表示するには:
並列クエリ処理のため、データは順不同で出力されます
テーブルを削除するには:
データテーブルを返さない正常なリクエストでは、レスポンスボディは空になります。

​
圧縮

圧縮は、大量のデータを送信する際のネットワークトラフィックを削減したり、圧縮済みのダンプを直接作成したりする場合に利用できます。 データ送信時には、ClickHouse の内部圧縮フォーマットを使用できます。圧縮されたデータは標準的ではないフォーマットのため、扱うには clickhouse-compressor プログラムが必要です。これは clickhouse-client パッケージとともにデフォルトでインストールされます。 データの insert 効率を高めるには、http_native_compression_disable_checksumming_on_decompress 設定を使用して、サーバー側のチェックサム検証を無効にしてください。 URL に compress=1 を指定すると、サーバーは送信するデータを圧縮します。URL に decompress=1 を指定すると、サーバーは POST method で渡されたデータを展開します。 HTTP 圧縮 を使用することもできます。ClickHouse は次の圧縮方式をサポートしています。
  • gzip
  • br
  • deflate
  • xz
  • zstd
  • lz4
  • bz2
  • snappy
圧縮された POST リクエストを送信するには、リクエスト header に Content-Encoding: compression_method を追加してください。 ClickHouse にレスポンスを圧縮させるには、リクエストに Accept-Encoding: compression_method header を追加してください。 すべての圧縮方式で、http_zlib_compression_level 設定を使用してデータの圧縮レベルを設定できます。
一部の HTTP クライアントは、デフォルトでサーバーからのデータを展開する場合があります (gzip および deflate) 。そのため、圧縮設定を正しく使用していても、展開後のデータを受け取ることがあります。

​
例

圧縮データをサーバーへ送信するには:
サーバーから圧縮データアーカイブを受け取るには:
サーバーから圧縮データを受信し、gunzip で展開後のデータを受け取るには:

​
デフォルトデータベース

database URL パラメータまたは X-ClickHouse-Database ヘッダーで、デフォルトのデータベースを指定できます。
デフォルトでは、サーバー設定に登録されているデータベースが既定のデータベースとして使用されます。初期状態では、これは default という名前のデータベースです。別の方法として、テーブル名の前にドット区切りでデータベース名を付けて、いつでもデータベースを指定できます。

​
認証

ユーザー名とパスワードは、次の3つの方法のいずれかで指定できます。
  1. HTTP Basic認証を使用する方法。
例:
  1. user および password の URL パラメータ内
パラメータが Web プロキシに記録され、ブラウザにキャッシュされる可能性があるため、この方法の使用は推奨されません
例:
  1. ‘X-ClickHouse-User’ および ‘X-ClickHouse-Key’ ヘッダーを使用する
例:
ユーザー名が指定されていない場合は、default が使用されます。パスワードが指定されていない場合は、空のパスワードが使用されます。 また、URL パラメータを使って、単一のクエリの処理に対する設定や、設定プロファイル全体を指定することもできます。 たとえば:
詳細については、以下を参照してください。

​
HTTPプロトコルでClickHouseセッションを使用する

HTTPプロトコルでもClickHouseセッションを使用できます。これを行うには、リクエストに session_id GET パラメータを追加する必要があります。セッションIDには任意の文字列を使用できます。 デフォルトでは、セッションは60秒間非アクティブな状態が続くと終了します。このタイムアウト (秒単位) を変更するには、サーバー設定の default_session_timeout を変更するか、リクエストに session_timeout GET パラメータを追加します。 セッションの状態を確認するには、session_check=1 パラメータを使用します。1つのセッション内で同時に実行できるクエリは1つだけです。 クエリの進行状況に関する情報は、X-ClickHouse-Progress レスポンスヘッダーで受け取ることができます。これを行うには、send_progress_in_http_headers を有効にします。 以下はヘッダーシーケンスの例です:
使用可能なヘッダーフィールドは次のとおりです。 実行中のリクエストは、HTTP接続が失われても自動的には停止しません。パースとデータのフォーマットはサーバー側で行われるため、ネットワーク越しでは非効率になる場合があります。 次のオプションパラメーターがあります。 HTTP インターフェイスでは、クエリのために外部データ (外部一時テーブル) を渡すこともできます。詳細については、“クエリ処理用の外部データ” を参照してください。

​
レスポンスのバッファリング

レスポンスのバッファリングはサーバー側で有効にできます。このために、次のURLパラメータが用意されています。
  • buffer_size
  • wait_end_of_query
次の設定も使用できます。 buffer_size は、サーバーのメモリ内で結果をバッファリングするバイト数を決定します。結果のボディがこのしきい値を超える場合、バッファはHTTPチャネルに書き込まれ、残りのデータはHTTPチャネルに直接送信されます。 レスポンス全体が確実にバッファリングされるようにするには、wait_end_of_query=1 を設定します。この場合、メモリに格納されないデータは、一時的なサーバーファイルにバッファリングされます。 たとえば:
レスポンスコードとHTTPヘッダーをクライアントに送信した後でクエリ処理エラーが発生する事態を避けるため、バッファリングを使用してください。この場合、エラーメッセージはレスポンスボディの末尾に書き込まれるため、クライアント側ではパース段階でしかエラーを検出できません。

​
クエリパラメータでロールを設定する

この機能は ClickHouse 24.4 で追加されました。 状況によっては、ステートメント自体を実行する前に、まず付与済みのロールを設定する必要があります。 ただし、マルチステートメントは許可されていないため、SET ROLE とステートメントを一緒に送信することはできません。
上記のコマンドを実行すると、エラーが発生します:
この制限を回避するには、代わりに role クエリパラメータを使用してください。
これは、ステートメントの前に SET ROLE my_role を実行するのと同じです。 さらに、複数の role クエリパラメータを指定することも可能です。
この場合、?role=my_role&role=my_other_role は、ステートメントの前に SET ROLE my_role, my_other_role を実行するのと同じように機能します。

​
HTTPレスポンスコードに関する注意点

HTTPプロトコルの制約上、HTTP 200のレスポンスコードでも、クエリが成功したとは限りません。 以下に例を示します。
この挙動が発生するのは、HTTP プロトコル の性質によるものです。まず HTTP ヘッダー が HTTP ステータスコード 200 とともに送信され、その後に HTTP ボディ が続き、さらにエラーがプレーンテキストとして ボディ 内に挿入されます。 この挙動は、Native、TSV、JSON など、どのフォーマットを使用しているかに関係ありません。エラーメッセージは常にレスポンスストリームの途中に現れます。 この問題は、wait_end_of_query=1 (Response Buffering) を有効にすることで緩和できます。この場合、HTTP ヘッダー の送信はクエリ全体の処理が完了するまで遅延されます。ただし、これでも問題が完全に解決するわけではありません。結果は依然として http_response_buffer_size の範囲内に収まる必要があり、さらに send_progress_in_http_headers などの設定によって ヘッダー の送信遅延が妨げられることもあるためです。
すべてのエラーを捕捉する唯一の方法は、必要なフォーマットでパースする前に HTTP ボディ を解析することです。
ClickHouse では、このような例外は http_write_exception_in_output_format=0 (デフォルト) の場合、使用するフォーマット (Native、TSV、JSON など) に関係なく、以下のような一貫した例外フォーマットになります。そのため、クライアント側でエラーメッセージを簡単にパースして抽出できます。
ここで、<TAG> は 16 バイトのランダムなタグで、X-ClickHouse-Exception-Tag レスポンスヘッダーで送信されるタグと同じものです。 <error message> は実際の例外メッセージです (正確な長さは <message_length> で確認できます) 。上で説明した例外ブロック全体のサイズは最大 16 KiB です。 以下は JSON フォーマットの例です
以下はCSVフォーマットの同様の例です

​
パラメータ付きクエリ

パラメータ付きのクエリを作成し、対応する HTTP リクエストパラメータから値を渡せます。詳しくは、CLI のパラメータ付きクエリを参照してください。

​
例

​
URL パラメータ内のタブ

クエリパラメータは escaped フォーマットとして解析されます。これには、たとえば NULL を \N として曖昧さなく解析できるといった利点があります。つまり、タブ文字は \t (または \ とタブ文字) としてエンコードする必要があります。たとえば、次の例では abc と 123 の間に実際のタブが含まれており、入力文字列は 2 つの値に分割されます。
ただし、URLパラメータで %09 を使って実際のタブ文字をエンコードしようとしても、正しくパースされません:
URL パラメータを使用する場合、\t は %5C%09 にエンコードする必要があります。例：

​
事前定義済み HTTP インターフェイス

ClickHouse は、HTTP インターフェイス経由で特定のクエリをサポートしています。たとえば、次のようにテーブルにデータを書き込むことができます。
ClickHouse は、Prometheus exporter のようなサードパーティーツールとの連携を容易にする、事前定義済み HTTP インターフェイスもサポートしています。では、例を見てみましょう。 まず、このセクションをサーバー設定ファイルに追加します。 http_handlers は複数の rule を含むように設定します。ClickHouse は受信した HTTP リクエストを rule で事前定義された種類に照らして照合し、最初に一致したルールのハンドラーを実行します。一致に成功すると、ClickHouse は対応する事前定義済みクエリを実行します。
config.xml
これで、Prometheusフォーマットのデータを取得するために、URL に直接リクエストできます。
http_handlers の設定オプションは次のとおりです。 rule では、以下のパラメータを設定できます。
  • method
  • headers
  • url
  • full_url
  • handler
各項目については以下で説明します。
  • method は、HTTPリクエストの method 部分の照合を担当します。method は、HTTPプロトコルにおける [method] (https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) の定義に完全に準拠しています。これは任意の設定です。設定ファイルで定義されていない場合、 HTTPリクエストの method 部分は照合されません。
  • url は、HTTPリクエストの URL 部分 (パスとクエリ文字列) の照合を担当します。 url に regex: プレフィックスが付いている場合は、RE2 の正規表現を使用します。 これは任意の設定です。設定ファイルで定義されていない場合、HTTPリクエストの URL 部分は照合されません。
  • full_url は url と同じですが、schema://host:port/path?query_string のような完全な URL を含みます。 注意: ClickHouse は “virtual hosts” をサポートしていないため、host は IP アドレスです (Host ヘッダーの値ではありません) 。
  • empty_query_string - リクエストにクエリ文字列 (?query_string) が含まれていないことを保証します
  • headers は、HTTPリクエストのヘッダー部分の照合を担当します。RE2 の正規表現と互換性があります。これは任意の 設定です。設定ファイルで定義されていない場合、HTTPリクエストのヘッダー部分は照合されません。
  • handler には主要な処理部分が含まれます。 指定できる type は次のとおりです: また、次のパラメータがあります:
    • query — predefined_query_handler type で使用し、ハンドラーが呼び出されたときにクエリを実行します。
    • query_param_name — dynamic_query_handler type で使用し、HTTPリクエストパラメータから query_param_name の値に対応する値を抽出して実行します。
    • status — static type で使用し、レスポンスのステータスコードを指定します。
    • content_type — 任意の type で使用し、レスポンスの content-type を指定します。
    • http_response_headers — 任意の type で使用し、レスポンスヘッダーの map を指定します。content type の設定にも使用できます。
    • response_content — static type で使用し、クライアントに送信するレスポンス内容を指定します。プレフィックス ‘file://’ または ‘config://’ を使用する場合は、file または設定から内容を取得してクライアントに送信します。
    • user - クエリの実行に使用する user です (default user は default です) 。 注意: この user の password を指定する必要はありません。
異なる type の設定方法については、次で説明します。

​
predefined_query_handler

predefined_query_handler では、Settings と query_params の値を設定できます。predefined_query_handler 型では query を設定できます。 query の値は predefined_query_handler 用の事前定義クエリで、HTTP リクエストが一致すると ClickHouse によって実行され、その結果が返されます。これは必須の設定です。 次の例では、max_threads および max_final_threads の設定値を定義し、その後 system table にクエリして、これらの設定が正しく適用されたかどうかを確認します。
query、play、ping などのデフォルトの handlers を維持するには、<defaults/> ルールを追加してください。
たとえば:

​
仮想パラメータ _request_body

URLパラメータ、ヘッダー、クエリパラメータに加えて、predefined_query_handler は特殊な仮想パラメータ _request_body もサポートしています。 これは、生の HTTP リクエストボディを文字列として保持します。 これにより、任意のデータフォーマットを受け付け、それをクエリ内で処理できる柔軟な REST API を作成できます。 たとえば、_request_body を使用して、POST リクエストで JSON データを受け取り、それをテーブルに挿入する REST エンドポイント を実装できます。
その後、このエンドポイントへデータを送信できます。
1 つの predefined_query_handler でサポートされる query は 1 つだけです。

​
dynamic_query_handler

dynamic_query_handler では、クエリを HTTP リクエストのパラメータとして記述します。predefined_query_handler との違いは、predefined_query_handler ではクエリを設定ファイルに記述する点です。query_param_name は dynamic_query_handler で設定できます。 ClickHouse は、HTTP リクエストの URL から query_param_name に対応する値を取り出して実行します。query_param_name のデフォルト値は /query です。これは任意の設定です。設定ファイルに定義がない場合、このパラメータは渡されません。 この機能を試すために、次の例では max_threads と max_final_threads の値を定義し、設定が正常に反映されたかどうかを確認する queries を実行します。 例:

​
static

static では、content_type、status、および response_content を返せます。response_content では、指定した内容を返せます。 例えば、“Say Hi!” というメッセージを返すには:
http_response_headers を使うと、content_type の代わりにコンテンツタイプを設定できます。
クライアントに送信されるconfigurationの内容を見つけます。
クライアントに送信するファイルの内容を確認するには:

​
redirect

redirect は location に 302 リダイレクトします たとえば、ClickHouse play の play に set user を自動的に追加するには、次のようにします:

​
HTTP レスポンスヘッダー

ClickHouse では、設定可能なあらゆる種類のハンドラーに適用できるカスタム HTTP レスポンスヘッダーを設定できます。これらのヘッダーは http_response_headers 設定で指定でき、ヘッダー名とその値を表すキー・バリューのペアを受け付けます。この機能は、カスタムのセキュリティヘッダーや CORS ポリシー、その他 ClickHouse HTTP インターフェイス全体で必要となる HTTP ヘッダー要件に対応する際に特に便利です。 たとえば、次のものに対してヘッダーを設定できます。
  • 通常のクエリエンドポイント
  • Web UI
  • ヘルスチェック
また、common_http_response_headers を指定することもできます。これらは、設定で定義されたすべての HTTP ハンドラーに適用されます。 ヘッダーは、設定された各ハンドラーの HTTP レスポンスに含まれます。 以下の例では、すべてのサーバーからのレスポンスに 2 つのカスタムヘッダー X-My-Common-Header と X-My-Custom-Header が含まれます。

​
HTTP streaming 中の例外発生時に有効な JSON/XML レスポンス

HTTP 経由でクエリを実行している際、データの一部がすでに送信された後で例外が発生することがあります。通常、例外はプレーンテキストでクライアントに送信されます。 データの出力に特定のデータフォーマットを使用していた場合、その出力は指定したデータフォーマットとしては無効になる可能性があります。 これを防ぐには、設定 http_write_exception_in_output_format (デフォルトでは無効) を使用します。この設定により、ClickHouse は指定したフォーマットで例外を書き出します (現在は XML および JSON* フォーマットをサポートしています) 。 例:
最終更新日 2026年7月2日