Skip to main content
Маршрутизация с учетом реплик (также известная как липкие сеансы, липкая маршрутизация или привязка сеанса) направляет связанные запросы на одну и ту же реплику ClickHouse. Используйте ее, если временные таблицы или именованное состояние сеанса должны оставаться доступными между запросами, если связанные запросы должны повторно использовать локальный кэш одной и той же реплики или если требуется согласованность чтения после записи между записью и последующими операциями чтения. Она работает по принципу best-effort и не гарантирует изоляцию. Прокси сопоставляет каждое значение маршрутизации с одной репликой. Сопоставление остается стабильным, пока число реплик не изменяется; при масштабировании сервиса значение может быть сопоставлено с другой репликой.
Требуется HTTP-интерфейсМаршрутизация с учетом реплик применяется на уровне прокси через интерфейс HTTP/HTTPS с использованием заголовка X-ClickHouse-Replica-Tag.Маршрутизация с учетом реплик в настоящее время недоступна через собственный протокол (собственный порт, например драйвер clickhouse-go, работающий в режиме собственного протокола по умолчанию). Клиентам собственного протокола необходимо перейти на HTTP и передавать значение маршрутизации в каждом запросе.

​
Предварительные требования

  • Вашему сервису требуется 2 или более реплики. В сервисе с одной репликой привязывать попросту не к чему.
  • По умолчанию доступно на уровне Enterprise после выхода возможности в GA.
  • Поддерживается в стандартных сервисах ClickHouse Cloud. BYOC пока не поддерживается.

​
Настройка маршрутизации с учетом реплик

Откройте тикет в службу поддержки и попросите включить HTTP-маршрутизацию запросов к репликам с закреплением сеанса. Укажите ID вашего сервиса и причину, по которой она вам нужна (временные таблицы, состояние сеанса, повторное использование кэша или согласованность чтения после записи). Перезапуск не требуется.

​
Маршрутизация на основе HTTP

Чтобы закрепить рабочую нагрузку за репликой, передавайте заголовок X-ClickHouse-Replica-Tag через HTTPS-интерфейс. Прокси применяет согласованное хеширование к значению заголовка, поэтому запросы с одинаковым значением направляются к одной и той же реплике, пока число реплик не меняется. Другое значение хешируется независимо и может попасть на ту же или другую реплику, но выбрать, какой именно реплике будет соответствовать значение, нельзя. Используйте существующее имя хоста сервиса. Специальные закреплённые имена хостов или изменения DNS не требуются. Значением заголовка может быть любая строка на ваш выбор, например имя приложения, идентификатор пользователя или метка рабочей нагрузки. Для запросов без заголовка сохраняется обычная балансировка нагрузки. Указывайте заголовок X-ClickHouse-Replica-Tag в каждом запросе:
Для clickhouse-go (v2) укажите Protocol: clickhouse.HTTP и передайте заголовок через параметр подключения HttpHeaders.
X-ClickHouse-Replica-Tag обеспечивает закрепление за репликой без создания HTTP-сеанса ClickHouse. Параллельные запросы могут использовать один и тот же тег, не сталкиваясь с SESSION_IS_LOCKED.

​
Согласованность чтения после записи

В сервисе с несколькими репликами запись, выполненная на одной реплике, может быть не видна на других, пока репликация не завершится. Отправьте запись с заголовком X-ClickHouse-Replica-Tag, а затем используйте то же значение заголовка при последующих операциях чтения. Прокси направит оба запроса на одну и ту же реплику, поэтому вы сможете прочитать собственную запись, даже если другие реплики всё ещё отстают. Этот подход подходит для рабочих нагрузок, при которых данные записываются, а затем сразу считываются, например для интерактивных приложений или задач ETL, проверяющих вставки перед продолжением работы. Для более строгих гарантий на всех репликах можно также установить select_sequential_consistency в значение 1 в ClickHouse Cloud.

​
Проверьте, к какой реплике вы подключены

Снова выполните пример SELECT hostName() с тем же значением X-ClickHouse-Replica-Tag. Пока число реплик не изменится, вы должны получить то же имя хоста. Другое значение заголовка может соответствовать другой реплике.

​
Ограничения маршрутизации с учетом реплик

​
Привязка меняется при изменении числа реплик

Масштабирование наружу или внутрь меняет кольцо хеширования маршрутизации. В результате запросы с одинаковым значением маршрутизации могут попасть на другую реплику. Если вы используете временные таблицы или настройки на уровне сеанса, будьте готовы создать их заново после переназначения.

​
Маршрутизация с учетом реплик не является изоляцией рабочих нагрузок

Липкая маршрутизация определяет только то, какая реплика обрабатывает запрос. Эта реплика по-прежнему может обслуживать и другой трафик. Для выделенных вычислительных ресурсов используйте compute-compute separation.

​
Частное сетевое подключение

Маршрутизация на основе HTTP работает с частным сетевым подключением на стандартном имени хоста вашего сервиса. Дополнительные записи DNS не требуются.

​
Для маршрутизации с учетом реплик требуется HTTP-протокол

Липкая маршрутизация использует HTTP-заголовок X-ClickHouse-Replica-Tag. Собственный бинарный протокол не передает это значение, по которому HTTP-прокси мог бы вычислить хеш, поэтому маршрутизация с учетом реплик недоступна через собственный протокол. Чтобы использовать эту возможность, клиентам собственного протокола необходимо перенести соответствующую рабочую нагрузку на HTTP-интерфейс.

​
Устранение неполадок

Запросы по-прежнему направляются на разные реплики при одном и том же значении маршрутизации
  • Убедитесь, что каждый запрос содержит заголовок X-ClickHouse-Replica-Tag.
  • Убедитесь, что во всех запросах используется точно одно и то же значение маршрутизации.
  • Немного подождите после включения. Изменения могут вступить в силу менее чем за минуту.
  • Проверьте, не изменилось ли недавно количество реплик: после масштабирования ожидается переназначение. Используйте SELECT hostName(), чтобы определить новое соответствие.
Последнее изменение 26 августа 2026 г.