概要
バックグラウンドクエリを使用すると、クライアントはrun_query_in_background=1 を設定することで、クライアントセッションとは独立して実行されるクエリを送信できます。送信後、ClickHouse サーバーは即座にクライアントへ応答し、クエリはサーバー側で完了 (成功または失敗) するまで実行され続けます。
クエリ実行をクライアントのネットワーク接続から切り離すことで、バックグラウンドタスクはクライアント側の切断や一時的なネットワーク障害の影響を一切受けません。
バックグラウンドクエリは主に、クライアント接続が切断されても停止させてはならない INSERT ... SELECT、
CREATE TABLE ... AS SELECT、CREATE MATERIALIZED VIEW ... POPULATE、OPTIMIZE TABLE ... FINAL
といった長時間実行される操作を対象としています。
すべてのクエリを接続から切り離せるわけではありません。拒否されるリクエストについては
サポートされていないクエリ形式を参照してください。
バックグラウンドクエリはサーバーの再起動をまたいで存続しません。サーバー停止時の動作は
shutdown_wait_unfinished_queries と shutdown_wait_unfinished によって制御されます。
サポートされないクエリ形式
バックグラウンドクエリは、それを送信した接続よりも長く存続します。そのため、サーバーはクエリを受け付けた時点で、そのクエリの実行に必要なものをすべて保持している必要があります。この条件を満たさないリクエストは、送信元の接続上で同期的に拒否され、クエリは開始されません。接続経由でストリーミングされるデータ
クエリのディスパッチ後もサーバーが送信元の接続からデータを読み取る必要がある場合、INSERT は拒否されます。
これは INSERT ... FORMAT ... と、input を介してデータを読み取るクエリの両方に影響する可能性があります。このようなリクエストは A query whose data streams over the connection cannot be run in the background というエラーで拒否されます:
clickhouse-client は INSERT ... FORMAT ... のデータを別々のパケットで送信するため、この形式がネイティブプロトコル上でバックグラウンド実行されることはありません。
HTTP 経由の場合、クエリ全体とそのデータが初期パースバッファに収まるのであれば、どちらの形式も受け付けられます。このバッファのサイズは max_query_size によって制限されます。
これには、input を通じてインラインのペイロードを読み取る HTTP クエリも含まれます。ボディがそれより大きい場合、バッファリングされたクエリテキストを超えてストリーミングが続くため、拒否されます。
このサイズ境界に依存しないでください。バックグラウンドで読み込む必要のあるデータには、INSERT ... SELECT や、url、s3 などのテーブル関数を使用してください。
その他の拒否されるリクエスト
この設定が分散クエリの secondary クエリに伝播されることはありません。バックグラウンドで実行される分散
INSERT は、
バックグラウンドの初期クエリ内で、分片ごとのクエリをフォアグラウンドで実行します。
バックグラウンドクエリを送信する
ネイティブTCPプロトコル
clickhouse-client では、run_query_in_background をコマンドライン設定として渡します。
SETTINGS 句を使用することもできます:
clickhouse-client はインラインのクエリ設定の大半を解析し、この設定セクションに含めて送信します。
ネイティブプロトコルのドライバーでは、代わりにクエリごとの設定マップで run_query_in_background を渡すことができ、SQLテキストを変更する必要はありません。
ネイティブプロトコルは、サーバー生成の query_id を返しません。ネイティブクライアント側で一意のIDを生成し、クエリと共に送信してください。
clickhouse-client --echo-query-id はこの処理を行い、クエリを送信する前にIDを出力します:
HTTP protocol
HTTP リクエストの場合は、run_query_in_background を URL パラメータとして渡します。
X-ClickHouse-Query-Id ヘッダーに含まれます。
query_id をURL パラメータとして送信してください。
こうすることで、clientはリクエストを送信する前からIDを把握できるため、レスポンスをまったく受け取れない場合でも、リクエストを受け付けたノード上でクエリを監視したり KILL したりできます:
SETTINGS 句でバックグラウンド実行を有効にすることはできません。
BAD_ARGUMENTS 例外を返します。HTTP ハンドラーは、リクエストボディがパースされる前に、デタッチされたクエリコンテキストを作成するかどうかを判断する必要があります。
この設定は URL で渡すか、ユーザーまたはプロファイルのレベルで設定してください。
実行状況の監視
query_id を使用して、クエリが現在実行中かどうかを確認します。
system.query_log を参照して最終的なステータスを確認します。
system.query_log に記録されます。
system.processes、system.query_log、KILL QUERY はノードローカルであり、それぞれ応答したサーバー上のクエリしか参照できません。バックグラウンドクエリは、それを受け付けたサーバーに属します。しかし、そのサーバーは、次のリクエストがロードバランサー経由で到達するサーバーとは限りません。代わりに、クラスター全体を参照してください。system.query_log についても同様で、キャンセルにはクラスター全体を対象とする形式を使用する必要があります:クエリログのフラッシュ遅延
エントリはsystem.query_log に反映される前にバッファリングされます。
セルフマネージドの ClickHouse では、サーバー設定例で query_log.flush_interval_milliseconds を 7500 に設定しています。
ClickHouse Cloud では、エントリが反映されるまで最大 30 秒かかることがあります。短時間で終了するバックグラウンドクエリを監視する際は、この遅延を考慮してください。
セルフマネージドのサーバーでは、十分な権限を持つユーザーがクエリログのフラッシュを強制的に実行できます。他のシステムログに影響を与えないよう、対象のログを明示的に指定してください:
system.query_log をローカルから参照できるようになるわけではないため、引き続き 実行の監視 で説明しているとおり clusterAllReplicas を通じてログを読み取ってください。