Skip to main content
El enrutamiento con reconocimiento de réplicas (también conocido como sesiones persistentes, enrutamiento con afinidad o afinidad de sesión) dirige las solicitudes relacionadas a la misma réplica de ClickHouse. Úselo cuando necesite que las tablas temporales o el estado de sesión con nombre sigan estando disponibles entre consultas, cuando quiera que las consultas relacionadas reutilicen las cachés locales de la misma réplica o cuando necesite consistencia de lectura después de la escritura entre una escritura y las lecturas posteriores. Funciona según el mejor esfuerzo y no garantiza el aislamiento. El proxy asigna cada valor de enrutamiento a una réplica. La asignación se mantiene estable mientras no cambie el número de réplicas; al escalar el servicio, el valor puede asignarse a una réplica diferente.
Requiere la interfaz HTTPEl enrutamiento con reconocimiento de réplicas se aplica en la capa de proxy a través de la interfaz HTTP/HTTPS mediante el encabezado X-ClickHouse-Replica-Tag.El enrutamiento con reconocimiento de réplicas no está disponible actualmente a través del protocolo nativo (puerto nativo; por ejemplo, el driver clickhouse-go en su modo nativo predeterminado). Los client del protocolo nativo deben cambiar a HTTP y enviar el valor de enrutamiento en cada solicitud.

​
Prerrequisitos

  • Tu servicio necesita 2 o más réplicas. En un servicio con una sola réplica, no hay ninguna a la que anclarlo.
  • Disponible en Enterprise de forma predeterminada cuando la función sea GA.
  • Compatible con los servicios estándar de ClickHouse Cloud. BYOC aún no es compatible.

​
Configuración del enrutamiento con reconocimiento de réplicas

Abre un ticket de soporte y solicita que se habilite el enrutamiento de réplicas con afinidad basado en HTTP. Incluye el ID de tu servicio y por qué lo necesitas (tablas temporales, estado de la sesión, reutilización de caché o consistencia de lectura después de la escritura). No es necesario reiniciar.

​
Enrutamiento basado en HTTP

Para asignar una carga de trabajo a una réplica concreta, envíe un encabezado X-ClickHouse-Replica-Tag a través de la interfaz HTTPS. El proxy aplica hash consistente al valor del encabezado, por lo que las solicitudes que lo comparten se dirigen a la misma réplica mientras el número de réplicas no cambie. Un valor distinto se procesa como hash de forma independiente y puede asignarse a la misma réplica o a otra, pero no puede elegir a qué réplica se asigna un valor. Use el nombre del host de su servicio existente. No se requieren nombres del host sticky especiales ni cambios en DNS. El valor del encabezado puede ser cualquier cadena que elija, como un nombre de aplicación, un ID de usuario o una etiqueta de carga de trabajo. Las solicitudes sin el encabezado mantienen el balanceo de carga normal. Establezca el encabezado X-ClickHouse-Replica-Tag en cada solicitud:
Para clickhouse-go (v2), configure Protocol: clickhouse.HTTP y pase el encabezado mediante la opción de conexión HttpHeaders.
X-ClickHouse-Replica-Tag proporciona afinidad con una réplica sin crear una sesión HTTP de ClickHouse. Las solicitudes concurrentes pueden reutilizar la misma etiqueta sin encontrarse con SESSION_IS_LOCKED.

​
Consistencia de lectura después de la escritura

En un servicio con varias réplicas, es posible que una escritura en una réplica no sea visible en las demás hasta que la replicación se ponga al día. Envíe la escritura con un encabezado X-ClickHouse-Replica-Tag y reutilice el mismo valor de encabezado en las lecturas posteriores. El proxy enruta ambas solicitudes a la misma réplica, por lo que puede leer su propia escritura incluso si las demás réplicas aún están retrasadas. Este patrón es útil para cargas de trabajo que escriben y luego leen inmediatamente los mismos datos, como aplicaciones interactivas o jobs de ETL que validan las inserciones antes de continuar. Para obtener garantías más amplias en todas las réplicas, también puede establecer select_sequential_consistency en 1 en ClickHouse Cloud.

​
Compruebe qué réplica se ha utilizado

Ejecute de nuevo el ejemplo SELECT hostName() con el mismo valor de X-ClickHouse-Replica-Tag. Debería obtener el mismo nombre del host mientras el número de réplicas no cambie. Un valor de encabezado diferente puede asignarse a otra réplica.

​
Limitaciones del enrutamiento con reconocimiento de réplicas

​
La afinidad cambia cuando cambia el número de réplicas

El escalado horizontal, tanto de ampliación como de reducción, cambia el anillo hash de enrutamiento. Las solicitudes que comparten el mismo valor de enrutamiento pueden acabar llegando a una réplica diferente. Si depende de tablas temporales o de configuración a nivel de sesión, prepárese para volver a crearlas tras una reasignación.

​
El enrutamiento con reconocimiento de réplicas no es aislamiento de cargas de trabajo

El enrutamiento con afinidad solo controla qué réplica gestiona una petición. Esa réplica puede seguir atendiendo otro tráfico. Para tener cómputo dedicado, usa compute-compute separation.

​
Redes privadas

El enrutamiento basado en HTTP funciona con redes privadas en el nombre del host habitual de tu servicio. No se requieren registros DNS adicionales.

​
El enrutamiento con reconocimiento de réplicas requiere el protocolo HTTP

El enrutamiento con afinidad se basa en el encabezado HTTP X-ClickHouse-Replica-Tag. El protocolo binario nativo no incluye este valor que el proxy HTTP pueda usar para calcular el hash, por lo que el enrutamiento con reconocimiento de réplicas no está disponible a través del protocolo nativo. Los clients del protocolo nativo deben trasladar la carga de trabajo correspondiente a la interfaz HTTP para usar esta funcionalidad.

​
Solución de problemas

Las consultas siguen llegando a réplicas distintas con el mismo valor de enrutamiento
  • Confirme que cada solicitud incluya el encabezado X-ClickHouse-Replica-Tag.
  • Confirme que cada solicitud utiliza exactamente el mismo valor de enrutamiento.
  • Espere unos instantes tras la activación. Los cambios pueden tardar menos de un minuto en aplicarse.
  • Compruebe si el número de réplicas ha cambiado recientemente; es normal que se reasignen después del escalado. Use SELECT hostName() para descubrir la nueva correspondencia.
Última modificación el 26 de agosto de 2026