Skip to main content
レプリカ対応ルーティング (sticky sessions、スティッキールーティング、session affinity とも呼ばれます) は、関連するリクエストを同じ ClickHouse レプリカにルーティングします。一時テーブル や 名前付きセッション状態 にクエリをまたいでアクセスできるようにしておく必要がある場合、または関連するクエリで同じレプリカのローカル cache を再利用したい場合に使用します。 これはベストエフォート型の仕組みであり、分離を保証するものではありません。スケーリング、アップグレード、再起動により、特定の session_id がどのレプリカに割り当てられるかが変わることがあります。
HTTPインターフェイスが必要ですレプリカ対応ルーティングは、HTTP/HTTPS インターフェイス 上のプロキシ層で session_id クエリパラメータ (下記参照) を使用して適用されます。これは ネイティブプロトコルでは利用できません (ネイティブポート。たとえば、デフォルトのネイティブモードで動作する clickhouse-go ドライバー) 。ネイティブプロトコルのクライアントは HTTP に切り替え、各リクエストで session_id を渡す必要があります。clickhouse-go (v2) の場合は、Protocol: clickhouse.HTTP を設定し、setting として session_id を渡します。ドライバーはこれを、プロキシがハッシュ化に使用する URL のクエリパラメータとして送信します。

​
前提条件

  • ご利用のサービスには 2 つ以上のレプリカ が必要です。単一レプリカのサービスでは、固定先となるレプリカがありません。
  • 稼働中 のサービス。アイドル状態のサービスを起動すると、session_id に対応するレプリカが変わることがあります。
  • この機能が GA になると、Enterprise ではデフォルトで利用可能になります。
  • 標準の ClickHouse Cloud サービスでサポートされています。BYOC は現時点ではサポートされていません。

​
レプリカ対応ルーティングの設定

サポートチケットを作成し、HTTP ベースのスティッキーなレプリカルーティングを有効にするよう依頼してください。サービス ID と、必要な理由 (一時テーブル、セッションの状態、または cache の再利用) を記載してください。有効化後は、HTTPS リクエストに ?session_id= を付けて送信してください。再起動は不要です。

​
HTTP ベースのルーティング (session_id)

ワークロードを特定のレプリカに固定するには、HTTPS インターフェイス で session_id クエリパラメータを設定します。プロキシは session_id に対してコンシステントハッシュを使用してレプリカを選択するため、同じ session_id を持つすべてのリクエストは、クラスターのトポロジが変わるまで同じサーバーにルーティングされます。 既存のサービスホスト名を使用します。特別なスティッキーホスト名や DNS の変更は必要ありません。
session_id=my-workload-1 を含むすべてのリクエストは、同じレプリカに振り分けられます。異なる session_id の値はそれぞれ独立してハッシュ化され、同じレプリカに振り分けられることもあれば、別のレプリカに振り分けられることもあります。マッピング自体には一貫性がありますが、特定の値がどのレプリカにマッピングされるかを選ぶことはできません。 session_id には任意の文字列を指定できます (アプリケーション名、ユーザー ID、またはワークロードラベル) 。session_id を付けないリクエストでは、通常の負荷分散が維持されます。 クエリパラメータを追加できる任意の HTTP クライアントが利用でき、curl、clickhouse-connect、JDBC/ODBC などが含まれます。clickhouse-go (v2) では、前述のとおり HTTP モードを使用してください。

​
どのレプリカに接続されているかを確認する

同じsession_idを使って、上記のSELECT hostName()の例をもう一度実行します。同じホスト名が返されるはずです。session_idが異なると、別のレプリカに割り当てられる場合があります。

​
サブドメインベースのルーティング (非推奨)

非推奨このサブドメインベースの仕組みは非推奨になりつつあり、新しいサービスでは今後有効にならなくなります。スケーラビリティに欠けるためです (sticky エンドポイントごとに専用の TLS 証明書が必要になります) 。代わりに HTTP ベースの session_id メソッド を使用してください。すでに sticky サブドメインを使用している場合は、session_id ルーティングを有効にするために support に連絡してください。これは破壊的変更であり、移行が必要になります。
以前は、レプリカ対応ルーティングを有効にすると、サービスのホスト名に対してワイルドカードサブドメインを利用できました。ホスト名が abcxyz123.us-west-2.aws.clickhouse.cloud のサービスでは、*.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud に一致する任意のホスト名 (例: aaa.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud) は、Envoy によって特定のレプリカに一貫してハッシュされました。元のホスト名では引き続き、デフォルトのルーティングアルゴリズムである LEAST_CONNECTION による負荷分散が使用されました。

​
レプリカ対応ルーティングの制約事項

​
サービス変更時にはスティッキー性が崩れることがあります

サービスに何らかの中断が発生すると、ルーティングのハッシュリングが変化します。これには、サーバーポッドの再起動 (バージョンのアップグレード、クラッシュ、垂直スケーリング) や、スケールアウト/スケールインが含まれます。その結果、同じ session_id を共有するリクエストが別のサーバーポッドに振り分けられる場合があります。一時テーブルやセッションレベルの設定に依存している場合は、再マップ後にそれらを再作成できるようにしておいてください。

​
レプリカ対応ルーティングはワークロードの分離ではありません

スティッキールーティングで制御できるのは、どのレプリカがリクエストを処理するかだけです。そのレプリカは、引き続きほかのトラフィックも処理する可能性があります。専用のコンピュートが必要な場合は、コンピュート-コンピュート分離を使用してください。 HTTP session_id ルーティングは、通常のサービスホスト名でプライベートネットワーキングを使用する場合は動作します。追加の DNS エントリは必要ありません。 一方、非推奨のサブドメイン方式では動作しません。*.sticky.* ホスト名パターン用の DNS を追加する必要があり、設定を誤るとレプリカ間で負荷が偏る可能性があります。

​
レプリカ対応ルーティングには HTTP プロトコルが必要です

スティッキールーティングは session_id クエリパラメータをキーにしていますが、これは HTTP/HTTPS インターフェイスにしか存在しません。ネイティブバイナリプロトコルには、プロキシがハッシュのキーとして使えるこの種のパラメータがないため、ネイティブプロトコルではレプリカ対応ルーティングを利用できません。現在、この機能を使うには、ネイティブプロトコルを使うクライアントは該当するワークロードを HTTP インターフェイスに移す必要があります。

​
トラブルシューティング

同じ session_id でも、クエリが引き続き別のレプリカに送られる
  • session_id が HTTPヘッダーではなく、URL のクエリパラメータ (?session_id=...) になっていることを確認してください。
  • 有効化後、少し待ってください。反映されるまで 1 分ほどかかる場合があります。
  • サービスが最近スケールまたは再起動したかどうかを確認してください。トポロジーの変更後に再マッピングが発生するのは想定どおりです。SELECT hostName() を使って新しいマッピングを確認してください。
Last modified on July 24, 2026