メインコンテンツまでスキップ
メインコンテンツまでスキップ

HTTPインターフェース

HTTPインターフェースを使用すると、どのプラットフォームでも、どのプログラミング言語からでも、ClickHouseをREST APIの形で利用できます。HTTPインターフェースはネイティブインターフェースよりも制限がありますが、言語サポートが優れています。

デフォルトでは、clickhouse-serverはポート8123でHTTPをリッスンします（これは設定で変更可能です）。HTTPSもデフォルトでポート8443で有効にできます。

パラメーターなしで GET / リクエストを送信すると、200レスポンスコードと、http_server_default_responseで定義されたデフォルト値の文字列「Ok.」（末尾に改行を含む）が返されます。

また、HTTPレスポンスコードの注意事項も参照してください。

時々、curl コマンドがユーザーのオペレーティングシステムで利用できないことがあります。UbuntuやDebianでは、sudo apt install curlを実行してください。実行する前に、このドキュメンテーションを参照してインストールしてください。

Web UIにはこちらからアクセスできます: http://localhost:8123/play。

Web UIはクエリ実行中の進行状況の表示、クエリのキャンセル、およびストリーミング結果をサポートしています。クエリパイプラインのチャートとグラフを表示するための隠れた機能も備えています。

Web UIは、あなたのようなプロフェッショナルのために設計されています。

ClickHouse Web UIのスクリーンショット

ヘルスチェックスクリプトでは、GET /ping リクエストを使用します。このハンドラーは常に「Ok.」（末尾に改行）を返します。バージョン18.12.13から利用可能です。また、レプリカの遅延を確認するために/replicas_statusも参照してください。

リクエストは、URLの 'query' パラメーターとして送信するか、POSTとして送信できます。また、クエリの先頭を 'query' パラメーターに、残りをPOSTで送信します（後でこれが必要な理由を説明します）。デフォルトでは、URLのサイズは1MiBに制限されており、http_max_uri_size設定で変更可能です。

成功した場合、200レスポンスコードとレスポンスボディ内の結果が返されます。エラーが発生した場合、500レスポンスコードとエラーメッセージがレスポンスボディに返されます。

GETメソッドを使用すると、'readonly' が設定されます。言い換えれば、データを変更するクエリには、POSTメソッドのみを使用できます。クエリ自体をPOSTボディまたはURLパラメーターのいずれかに送信できます。

例:

ご覧の通り、curl はスペースをURLエスケープする必要があるため、やや不便です。wgetはすべてを自動でエスケープしますが、HTTP 1.1でのkeep-aliveおよびTransfer-Encoding: chunked使用時にはあまりうまく動作しないため、使用を推奨しません。

クエリの一部がパラメーターに送信され、別の部分がPOSTで送信される場合、これらの二つのデータ部分の間に改行が挿入されます。 例（これは機能しません）:

デフォルトでは、データはTabSeparated形式で返されます。

他のフォーマットを要求するには、クエリのFORMAT句を使用します。

また、'default_format' URLパラメーターまたは'X-ClickHouse-Format'ヘッダーを使用して、TabSeparated以外のデフォルト形式を指定できます。

データを送信するためのPOSTメソッドは、INSERTクエリに必要です。この場合、URLパラメーターにクエリの最初の部分を記述し、POSTを使用して挿入するデータを渡します。挿入するデータは、例えばMySQLからのタブ区切りのダンプである可能性があります。この方法で、INSERTクエリはMySQLのLOAD DATA LOCAL INFILEに置き換えられます。

例

テーブルの作成:

データ挿入のためにお馴染みのINSERTクエリを使用:

クエリとは別にデータを送信できます:

任意のデータフォーマットを指定できます。'Values'形式は、INSERT INTO t VALUESを書くときと同じです。

タブ区切りのダンプからデータを挿入するには、対応するフォーマットを指定します:

テーブルの内容を読み取ります。データは並行クエリ処理のために順不同で出力されます:

テーブルを削除します。

データテーブルを返さない成功したリクエストは、空のレスポンスボディが返されます。

圧縮​

大量のデータを送信する際や即座に圧縮されたダンプを作成する際には、圧縮を利用できます。

データを送信する際に内部のClickHouse圧縮フォーマットを使用することができます。圧縮データは非標準フォーマットであり、これで作業するにはclickhouse-compressorプログラムが必要です。このプログラムはclickhouse-clientパッケージと共にインストールされます。データ挿入の効率を高めるために、http_native_compression_disable_checksumming_on_decompress設定を使ってサーバー側のチェックサム検証を無効にすることができます。

URLにcompress=1を指定すると、サーバーは送信するデータを圧縮します。URLにdecompress=1を指定すると、サーバーはPOSTメソッドで渡すデータを解凍します。

HTTP圧縮を使用することもできます。ClickHouseは次の圧縮メソッドをサポートしています：

  • gzip
  • br
  • deflate
  • xz
  • zstd
  • lz4
  • bz2
  • snappy

圧縮されたPOSTリクエストを送信するには、リクエストヘッダーにContent-Encoding: compression_methodを追加します。ClickHouseにレスポンスを圧縮させるためには、enable_http_compression設定で圧縮を有効にし、リクエストにAccept-Encoding: compression_methodヘッダーを追加します。すべての圧縮メソッドに対して、http_zlib_compression_level設定でデータの圧縮レベルを設定できます。

参考

一部のHTTPクライアントはデフォルトでサーバーからのデータを解凍する場合があり（gzipおよび deflate）、圧縮設定を正しく使用しても解凍されたデータを受け取ることがあるかもしれません。

例

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

'database' URLパラメーターまたは'X-ClickHouse-Database'ヘッダーを使用して、デフォルトのデータベースを指定できます。

デフォルトでは、サーバー設定に登録されているデータベースがデフォルトのデータベースとして使用されます。デフォルトでは、これは'default'という名前のデータベースです。もしくは、テーブル名の前にドットを付けてデータベースを常に指定することができます。

ユーザー名とパスワードは、以下のいずれかの3つの方法で指定できます：

  1. HTTPベーシック認証を使用します。例：
  1. 'user'と'password'のURLパラメーターに設定します（この方法は推奨しません。パラメーターがWebプロキシにログされ、ブラウザにキャッシュされる可能性があるため）。例：
  1. 'X-ClickHouse-User'と'X-ClickHouse-Key'ヘッダーを使用します。例：

ユーザー名が指定されていない場合、defaultという名前が使用されます。パスワードが指定されていない場合、空のパスワードが使用されます。 URLパラメーターを使用して、単一クエリの処理設定や、全体の設定プロファイルを指定することも可能です。例：http://localhost:8123/?profile=web&max_rows_to_read=1000000000&query=SELECT+1

詳細については、設定セクションを参照してください。

他のパラメーターに関する情報は、「SET」セクションを参照してください。

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

HTTPプロトコルでClickHouseセッションを使用することもできます。これを行うには、リクエストにsession_id GETパラメーターを追加する必要があります。セッションIDには任意の文字列を使用できます。デフォルトでは、60秒間の非アクティブ状態が続いた後にセッションが終了します。このタイムアウト（秒単位）を変更するには、サーバー設定でdefault_session_timeout設定を変更するか、リクエストにsession_timeout GETパラメーターを追加します。セッションのステータスを確認するためには、session_check=1パラメーターを使用します。単一のセッション内で同時に実行できるクエリは1つだけです。

X-ClickHouse-Progressレスポンスヘッダーでクエリの進行状況に関する情報を取得できます。これを行うには、send_progress_in_http_headersを有効にします。ヘッダーのシーケンスの例：

利用可能なヘッダーフィールド：

  • read_rows — 読み取られた行数。
  • read_bytes — 読み取られたデータのバイト数。
  • total_rows_to_read — 読み取るべき行数の合計。
  • written_rows — 書き込まれた行数。
  • written_bytes — 書き込まれたデータのバイト数。

リクエストが実行中でHTTP接続が失われた場合、自動的に停止することはありません。解析とデータのフォーマットはサーバー側で行われ、ネットワークの使用は効果的でない場合があります。 オプショナルな'query_id'パラメーターをクエリID（任意の文字列）として渡すことができます。詳細については、「設定、実行中のクエリの置き換え」セクションを参照してください。

オプショナルな'quota_key'パラメーターをクォータキー（任意の文字列）として渡すことができます。詳細については、「クォータ」セクションを参照してください。

HTTPインターフェースでは、クエリのために外部データ（外部一時テーブル）を渡すことができます。詳細については、「クエリ処理のための外部データ」セクションを参照してください。

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

サーバー側でレスポンスバッファリングを有効にできます。これを目的とするために、buffer_sizeおよびwait_end_of_query URLパラメータが用意されています。http_response_buffer_size および http_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を有効にすることができます（レスポンスバッファリング）。この場合、HTTPヘッダーの送信はクエリが完全に解決されるまで遅延します。しかし、これは問題を完全には解決しません、なぜなら結果はまだhttp_response_buffer_size内に収まらなければならず、send_progress_in_http_headersなどの他の設定がヘッダーの遅延に干渉する可能性があるからです。 すべてのエラーをキャッチする唯一の方法は、要求されたフォーマットを使用する前にHTTPボディを解析することです。

パラメータ付きクエリ​

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

例​

URLパラメーターのタブ​

クエリパラメータは「エスケープ」形式から解析されます。これは、NULLを\Nとしてあいまいなく解析する可能性などの利点があります。これを意味するのは、タブ文字を\t（または\とタブ）としてエンコードする必要があるということです。例えば、次のようなタブがabcと123の間に存在し、入力文字列が二つの値に分割されます：

しかし、実際のタブをURLパラメータで%09を使用してエンコードしようとすると、正しく解析されません：

URLパラメータを使用する場合、\tを%5C%09としてエンコードする必要があります。それにより、次のように記述できます：

事前定義されたHTTPインターフェース​

ClickHouseはHTTPインターフェースを通じて特定のクエリをサポートしています。例えば、次のようにテーブルにデータを書き込むことができます：

ClickHouseは事前定義されたHTTPインターフェースもサポートしており、Prometheusエクスポーターなどのサードパーティツールとの統合を容易にします。

例：

  • まず、このセクションをサーバー設定ファイルに追加します：
  • これで、Prometheus形式のデータを求めてURLに直接リクエストできるようになります：

設定がconfig.xmlファイルに行われていて、http_handlersが多数のrulesを含むことに気づいたでしょう。ClickHouseは受信したHTTPリクエストを事前定義されたタイプに一致させ、最初に一致したルールがハンドラーを実行します。その後、ClickHouseは一致が成功すれば、それに応じた事前定義クエリを実行します。

今や、ruleはmethod、headers、url、handlerを設定することができます：

  • methodはHTTPリクエストのメソッド部分のマッチングを担当します。methodはHTTPプロトコルの定義に完全に準拠します。methodはオプショナルな設定です。設定ファイルに定義されていない場合、HTTPリクエストのメソッド部分とは一致しません。

  • urlはHTTPリクエストのURL部分の一致を担当します。これはRE2の正規表現と互換性があります。これはオプショナルな設定です。設定ファイルに定義されていない場合、HTTPリクエストのURL部分とは一致しません。

  • headersはHTTPリクエストのヘッダー部分の一致を担当します。これはRE2の正規表現と互換性があります。これはオプショナルな設定です。設定ファイルに定義されていない場合、HTTPリクエストのヘッダー部分とは一致しません。

  • handlerは主な処理部分を含みます。現在、handlerはtype、status、content_type、http_response_headers、response_content、query、query_param_nameを設定できます。 typeは現在、3つのタイプ：predefined_query_handler、dynamic_query_handler、staticをサポートしています。

    • query — predefined_query_handlerタイプで使用し、ハンドラーが呼び出されたときにクエリを実行します。

    • query_param_name — dynamic_query_handlerタイプで使用し、HTTPリクエストパラメーター内のquery_param_nameに対応する値を抽出して実行します。

    • status — staticタイプで使用し、レスポンスステータスコードです。

    • content_type — 任意のタイプで使用し、レスポンスコンテンツタイプです。

    • http_response_headers — 任意のタイプで使用し、レスポンスヘッダーのマップです。コンテンツタイプを設定するためにも使用できます。

    • response_content — staticタイプで使用し、クライアントに送信されるレスポンスコンテンツです。file://またはconfig://のプレフィックスを使用する場合は、クライアントに送信するファイルまたは設定からコンテンツを見つけます。

次に、異なる type の設定方法を示します。

predefined_query_handler​

predefined_query_handlerはSettingsとquery_paramsの値を設定することをサポートしています。predefined_query_handlerタイプの中でqueryを設定できます。

queryの値は、HTTPリクエストが一致した場合にClickHouseが実行するpredefined_query_handlerの事前定義クエリです。これは必須の設定です。

次の例は、max_threads と max_final_threads 設定の値を定義し、これらの設定が正常に設定されているかどうかをチェックするためにシステムテーブルをクエリします。

注記

デフォルトのhandlers（query、play、pingなど）を保持するためには、<defaults/>ルールを追加してください。

例：

注記

1つのpredefined_query_handler内では、1つのqueryのみをサポートされます。

dynamic_query_handler​

dynamic_query_handlerでは、クエリがHTTPリクエストのパラメーターの形で記述されます。これに対する違いは、predefined_query_handlerではクエリが設定ファイルに書かれているという点です。dynamic_query_handlerでquery_param_nameを設定できます。

ClickHouseはHTTPリクエストのURL内のquery_param_nameに対応する値を抽出し、実行します。query_param_nameのデフォルト値は/queryです。これはオプショナルな設定です。設定ファイルに定義がない場合、このパラメーターは渡されません。

この機能を試してみるために、例では、max_threadsおよびmax_final_threadsの値を定義し、設定が正常に行われたかどうかを確認します。

例：

static​

static は content_type 、status および response_content を返すことができます。 response_content は指定されたコンテンツを返すことができます。

例:

メッセージを返す。

http_response_headers は content_type の代わりにコンテンツタイプを設定するために使用できます。

クライアントに送信される構成からコンテンツを見つけます。

ファイルからクライアントに送信されるコンテンツを見つけます。

Valid JSON/XML response on exception during HTTP streaming​

HTTP 経由でクエリを実行中に、データの一部がすでに送信されているときに例外が発生することがあります。 通常、特定のデータ形式が出力データに使用された場合でも、プレーンテキストでクライアントに例外が送信され、出力が指定されたデータ形式の観点から無効になる場合があります。 これを防ぐために、http_write_exception_in_output_format 設定（デフォルトで有効）を使用すると、ClickHouse に指定された形式で例外を書き込むよう指示できます（現在、XMLおよびJSON形式でサポートされています）。

例: