HTTPインターフェース
前提条件
この記事の例では、次のものが必要です：
- 稼働中のClickHouseサーバーインスタンス
curlがインストールされていること。UbuntuやDebianの場合、sudo apt install curlを実行するか、このドキュメントを参照してインストール手順を確認してください。
概要
HTTPインターフェースを使用すると、REST APIの形式で任意のプラットフォームから任意のプログラミング言語でClickHouseを利用できます。HTTPインターフェースはネイティブインターフェースよりも機能が制限されていますが、より良い言語サポートがあります。
デフォルトでは、clickhouse-serverは次のポートでリッスンしています：
- HTTP用のポート8123
- HTTPS用のポート8443が有効にできます
パラメータなしでGET /リクエストを行うと、ステータスコード200が返され、文字列 "Ok." が付随します。
"Ok."はhttp_server_default_responseで定義されたデフォルト値であり、変更することができます。
また、HTTPレスポンスコードの注意事項も参照してください。
Webユーザーインターフェース
ClickHouseにはウェブユーザーインターフェースが含まれており、次のアドレスからアクセスできます：
ウェブUIは、クエリの実行時の進捗表示、クエリのキャンセル、および結果のストリーミングをサポートしています。 クエリパイプラインのグラフやチャートを表示する秘密の機能があります。
ウェブ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メソッドを使用したリクエストは「読み取り専用」です。これは、データを変更するクエリにはPOSTメソッドのみを使用できることを意味します。 クエリ自体をPOSTボディに送信することも、URLパラメータで送信することもできます。以下にいくつかの例を示します。
以下の例では、SELECT 1クエリを送信するためにcurlが使用されています。スペースはURLエンコードされた形式であることに注意してください：%20。
この例では、wgetが-nv（非冗長）および-O-パラメータを使用して結果をターミナルに出力しています。
この場合、スペースをURLエンコードする必要はありません：
この例では、生のHTTPリクエストをnetcatにパイプしています：
ご覧の通り、curlコマンドは、スペースをURLでエスケープする必要があるため、やや不便です。
wgetはすべてを自動的にエスケープしますが、HTTP 1.1においてkeep-aliveやTransfer-Encoding: chunkedを使用する場合にうまく機能しないため、使用は推奨しません。
クエリの一部がパラメータで送信され、一部がPOSTで送信される場合、これら二つのデータ部分の間に改行が挿入されます。 例えば、これは機能しません：
デフォルトでは、データはTabSeparated形式で返されます。
FORMAT句をクエリに使用して、他のフォーマットを要求できます。例えば：
default_format URLパラメータまたはX-ClickHouse-Formatヘッダーを使用して、TabSeparated以外のデフォルトフォーマットを指定できます。
HTTP/HTTPS経由での挿入クエリ
データを転送するのにPOSTメソッドが必要です。この場合、クエリの最初の部分をURLパラメータに記述し、データを送信するのにPOSTを使用します。挿入するデータは、例えばMySQLのタブ区切りダンプであることがあります。このようにして、INSERTクエリはMySQLのLOAD DATA LOCAL INFILEを置き換えます。
例
テーブルを作成するには：
データ挿入のために馴染みのあるINSERTクエリを使用するには：
クエリとは別にデータを送信するには：
任意のデータフォーマットを指定できます。例えば、INSERT INTO t VALUESを書くときと同じフォーマットである'Values'フォーマットを指定できます：
タブ区切りダンプからデータを挿入するには、対応するフォーマットを指定します：
テーブルの内容を読み取るには：
並行クエリ処理のため、データはランダムな順序で出力されます
テーブルを削除するには：
データテーブルを返さない成功リクエストの場合、空のレスポンスボディが返されます。
圧縮
圧縮は、大量のデータを転送する際にネットワークトラフィックを削減するためや、一時的に圧縮されたダンプを作成するために使用できます。
データを転送する際に内部ClickHouse圧縮フォーマットを使用できます。圧縮されたデータは非標準フォーマットであり、clickhouse-compressorプログラムを使用して取り扱う必要があります。これはデフォルトでclickhouse-clientパッケージにインストールされています。
データ挿入の効率を高めるために、http_native_compression_disable_checksumming_on_decompress設定を使用して、サーバー側のチェックサム検証を無効にします。
URLに compress=1 を指定すると、サーバーは送信するデータを圧縮します。URLに decompress=1 を指定すると、サーバーはPOSTメソッドで渡されたデータを解凍します。
HTTP圧縮を使用することもできます。ClickHouseは次の圧縮方式をサポートしています：
gzipbrdeflatexzzstdlz4bz2snappy
圧縮されたPOSTリクエストを送信するには、リクエストヘッダーContent-Encoding: compression_methodを追加します。
ClickHouseがレスポンスを圧縮するためには、enable_http_compression設定を有効にし、リクエストにAccept-Encoding: compression_methodヘッダーを追加します。
データ圧縮レベルは、http_zlib_compression_level設定を使用してすべての圧縮方法に対して設定できます。
一部のHTTPクライアントは、デフォルトでサーバーからのデータを解凍する可能性があり（gzipとdeflateで）、圧縮設定を正しく使用している場合でも解凍されたデータが返されることがあります。
例
サーバーに圧縮データを送信するには：
サーバーから圧縮データアーカイブを受信するには：
サーバーから圧縮データを受信し、gunzipを使用して解凍データを受信するには：
デフォルトデータベース
database URLパラメータまたは X-ClickHouse-Database ヘッダーを使用して、デフォルトデータベースを指定できます。
デフォルトでは、サーバー設定に登録されているデータベースがデフォルトデータベースとして使用されます。初期状態では、これはdefaultという名前のデータベースです。あるいは、常にテーブル名の前にドットを付けてデータベースを指定できます。
認証
ユーザー名とパスワードは、次の3つの方法のいずれかで指定できます：
- HTTP基本認証を使用。
例えば：
userおよびpasswordURLパラメータに指定
この方法は、パラメータがWebプロキシによってログに記録され、ブラウザにキャッシュされる可能性があるため、推奨しません。
例えば：
- '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を有効にします。
以下は、ヘッダーのシーケンスの例です：
可能なヘッダーフィールドは次の通りです：
| ヘッダーフィールド | 説明 |
|---|---|
read_rows | 読まれた行の数。 |
read_bytes | 読まれたデータのサイズ（バイト）。 |
total_rows_to_read | 読み取る必要のある行の合計数。 |
written_rows | 書き込まれた行の数。 |
written_bytes | 書き込まれたデータのサイズ（バイト）。 |
HTTP接続が失われても、リクエストは自動的に停止しません。パースとデータフォーマットはサーバー側で行われ、ネットワークを利用することが非効率的な場合があります。
以下のオプションパラメータがあります：
| パラメータ | 説明 |
|---|---|
query_id（オプション） | クエリIDとして渡すことができます（任意の文字列）。replace_running_query |
quota_key（オプション） | クオータキーとして渡すことができます（任意の文字列）。"クオータ" |
HTTPインターフェースを介して、クエリのための外部データ（外部一時テーブル）を渡すことができます。詳細は、"クエリ処理のための外部データ"を参照してください。
レスポンスバッファリング
レスポンスバッファリングはサーバー側で有効にできます。次のURLパラメータが提供されています：
buffer_sizewait_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を明示的に解析できるという利点があります。つまり、タブ文字は\\t（または\とタブ）としてエンコードする必要があります。例えば、次のようにabcと123の間に実際のタブが含まれていて、入力文字列が2つの値に分割されます：
ただし、URLパラメータで実際のタブを%09を使ってエンコードしようとすると、正しく解析されません：
URLパラメータを使用している場合、\tを%5C%09のようにエンコードする必要があります。例えば：
予め定義されたHTTPインターフェース
ClickHouseは特定のクエリをHTTPインターフェースを介してサポートしています。例えば、テーブルにデータを書き込むには次のようにします：
ClickHouseは、Prometheusエクスポータなどのサードパーティツールとの統合を容易にするための予め定義されたHTTPインターフェースもサポートしています。例を見てみましょう。
まず、サーバー設定ファイルにこのセクションを追加します。
http_handlersは複数のruleを含むように設定されます。ClickHouseは受信したHTTPリクエストをrule内の予め定義されたタイプにマッチさせ、最初にマッチしたルールがハンドラーを実行します。次に、ClickHouseはマッチが成功した場合に対応する予め定義されたクエリを実行します。
これで、Prometheusフォーマットのデータを取得するためにURLに直接リクエストできます：
http_handlersの構成オプションは、次のように機能します。
ruleは次のパラメータを設定できます：
methodheadersurlhandler
これらは以下で説明されます：
-
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は現在、predefined_query_handler、dynamic_query_handler、staticの3つのタイプをサポートしています。query—predefined_query_handlerタイプで使用し、ハンドラー呼び出し時にクエリを実行します。query_param_name—dynamic_query_handlerタイプで使用し、HTTPリクエストパラメータ内のquery_param_name値に対応する値を抽出して実行します。status—staticタイプで使用し、レスポンスのステータスコードです。content_type— いずれのタイプでも使用可能で、レスポンスのcontent-typeです。http_response_headers— いずれのタイプでも使用可能で、レスポンスヘッダーのマップです。コンテンツタイプを設定するためにも使用できます。response_content—staticタイプで使用し、ファイルまたは構成からクライアントに送信されるレスポンスコンテンツです。
さまざまな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設定の値を定義し、その後、これらの設定が成功裏に設定されたかどうかを確認するためにシステムテーブルをクエリしています。
query、play、pingのようなデフォルトのhandlersを維持するためには、<defaults/>ルールを追加してください。
例えば：
1つのpredefined_query_handlerでは、1つのqueryのみがサポートされています。
dynamic_query_handler
dynamic_query_handlerでは、クエリがHTTPリクエストのパラメータとして記述されます。predefined_query_handlerではクエリが設定ファイルに記述されるのとは異なります。query_param_nameはdynamic_query_handlerに設定できます。
ClickHouseは、HTTPリクエストのURL内のquery_param_name値に対応する値を抽出して実行します。query_param_nameのデフォルト値は/queryです。これはオプションの構成です。構成ファイルに定義がない場合、そのパラメータは渡されません。
この機能を試すために、次の例ではmax_threadsとmax_final_threadsの値を定義し、設定が成功裏に設定されたかどうかを確認します。
例：
static
static は content_type、status および response_content を返すことができます。response_content は指定されたコンテンツを返します。
例えば、メッセージ "Say Hi!" を返すには：
http_response_headers は content_type の代わりにコンテンツタイプを設定するために使用できます。
クライアントに送信される設定からコンテンツを見つけます。
クライアントに送信されるファイルからコンテンツを見つけるには：
Valid JSON/XML response on exception during HTTP streaming
クエリの実行中にHTTPを介して例外が発生することがあります。この場合、データの一部がすでに送信されている場合があります。通常、例外はプレーンテキストでクライアントに送信されます。
特定のデータ形式を使用してデータを出力していた場合、出力が指定されたデータ形式にとって無効になる可能性があります。
これを防ぐために、設定 http_write_exception_in_output_format を使用できます（デフォルトで有効）。これにより、ClickHouseは指定された形式で例外を書き込むことができます（現在XMLおよびJSON形式でサポートされています）。
例：
