Skip to main content
Le routage tenant compte des répliques (également appelé sessions sticky, routage sticky ou affinité de session) achemine les requêtes liées vers la même réplique ClickHouse. Utilisez-le lorsque des tables temporaires ou un état de session nommé doivent rester accessibles d’une requête à l’autre, lorsque vous souhaitez que des requêtes liées réutilisent les caches locaux d’une même réplique, ou lorsque vous avez besoin d’une cohérence lecture après écriture entre une écriture et les lectures qui suivent. Il est fourni au mieux et ne garantit pas l’isolation. Le proxy associe chaque valeur de routage à une réplique. Cette association reste stable tant que le nombre de répliques ne change pas ; la mise à l’échelle du service peut toutefois associer cette valeur à une autre réplique.
Nécessite l’interface HTTPLe routage tenant compte des répliques est appliqué au niveau du proxy via l’interface HTTP/HTTPS à l’aide de l’en-tête X-ClickHouse-Replica-Tag.Le routage tenant compte des répliques est actuellement indisponible via le protocole natif (port natif, par exemple avec le driver clickhouse-go dans son mode natif par défaut). Les clients utilisant le protocole natif doivent passer à HTTP et envoyer la valeur de routage avec chaque requête.

​
Prérequis

  • Votre service doit disposer d’au moins 2 répliques. Sur un service à réplique unique, il n’y a rien à épingler.
  • Disponible par défaut sur Enterprise lorsque la fonctionnalité est en GA.
  • Pris en charge sur les services ClickHouse Cloud standard. BYOC n’est pas encore pris en charge.

​
Configuration du routage tenant compte des répliques

Ouvrez un ticket d’assistance et demandez l’activation du routage sticky HTTP vers les répliques. Indiquez l’ID de votre service et la raison pour laquelle vous en avez besoin (tables temporaires, état de la session, réutilisation du cache ou cohérence lecture après écriture). Aucun redémarrage n’est nécessaire.

​
Routage HTTP

Pour associer une charge de travail à une réplique, envoyez un en-tête X-ClickHouse-Replica-Tag via l’interface HTTPS. Le proxy applique un hachage cohérent à la valeur de l’en-tête : les requêtes partageant cette valeur sont donc dirigées vers la même réplique tant que le nombre de répliques reste inchangé. Une valeur différente est hachée indépendamment et peut être associée à la même réplique ou à une autre, mais vous ne choisissez pas à quelle réplique une valeur est associée. Utilisez le nom d’hôte existant de votre service. Aucun nom d’hôte sticky spécifique ni aucune modification DNS ne sont nécessaires. La valeur de l’en-tête peut être n’importe quelle chaîne de votre choix, par exemple un nom d’application, un ID utilisateur ou un label de charge de travail. Les requêtes sans cet en-tête conservent l’équilibrage de charge habituel. Définissez l’en-tête X-ClickHouse-Replica-Tag pour chaque requête :
Pour clickhouse-go (v2), définissez Protocol: clickhouse.HTTP et transmettez l’en-tête à l’aide de l’option de connexion HttpHeaders.
X-ClickHouse-Replica-Tag assure une affinité avec une réplique sans créer de session HTTP ClickHouse. Les requêtes concurrentes peuvent réutiliser le même tag sans rencontrer l’erreur SESSION_IS_LOCKED.

​
Cohérence lecture après écriture

Dans un service comportant plusieurs répliques, une écriture effectuée sur une réplique peut ne pas être visible sur les autres tant que la réplication n’a pas rattrapé son retard. Envoyez votre écriture avec un en-tête X-ClickHouse-Replica-Tag, puis réutilisez la même valeur d’en-tête pour les lectures suivantes. Le proxy achemine les deux requêtes vers la même réplique : vous lisez donc votre propre écriture, même si les autres répliques sont encore en retard. Ce modèle convient aux charges de travail qui écrivent des données, puis les relisent immédiatement, comme les applications interactives ou les jobs ETL qui valident les inserts avant de poursuivre. Pour des garanties plus étendues sur l’ensemble des répliques, vous pouvez également définir select_sequential_consistency sur 1 dans ClickHouse Cloud.

​
Vérifier quelle réplique est utilisée

Exécutez à nouveau l’exemple SELECT hostName() avec la même valeur X-ClickHouse-Replica-Tag. Vous devriez obtenir le même nom d’hôte tant que le nombre de répliques reste inchangé. Une valeur d’en-tête différente peut être associée à une autre réplique.

​
Limites du routage tenant compte des réplicas

​
La persistance change lorsque le nombre de répliques change

La mise à l’échelle horizontale, à la hausse comme à la baisse, modifie l’anneau de hachage du routage. Des requêtes partageant la même valeur de routage peuvent alors être dirigées vers une autre réplique. Si vous vous appuyez sur des tables temporaires ou des paramètres au niveau de la session, soyez prêt à les recréer après une réaffectation.

​
Le routage tenant compte des réplicas n’est pas une isolation des charges de travail

Le routage sticky contrôle uniquement quelle réplique traite une requête. Cette réplique peut tout de même servir d’autres requêtes. Pour un compute dédié, utilisez la séparation compute-compute.

​
Mise en réseau privée

Le routage HTTP fonctionne avec la mise en réseau privée sur le nom d’hôte habituel de votre service. Aucune entrée DNS supplémentaire n’est requise.

​
Le routage tenant compte des répliques nécessite le protocole HTTP

Le routage sticky repose sur l’en-tête HTTP X-ClickHouse-Replica-Tag. Le protocole binaire natif ne transporte pas cette valeur sur laquelle le proxy HTTP puisse calculer un hash ; le routage tenant compte des répliques n’est donc pas disponible avec le protocole natif. Les clients utilisant le protocole natif doivent faire passer la charge de travail concernée par l’interface HTTP pour utiliser cette fonctionnalité.

​
Résolution des problèmes

Les requêtes sont toujours dirigées vers différentes répliques avec la même valeur de routage
  • Vérifiez que chaque requête inclut l’en-tête X-ClickHouse-Replica-Tag.
  • Vérifiez que chaque requête utilise exactement la même valeur de routage.
  • Attendez un instant après l’activation. La modification peut prendre moins d’une minute avant de prendre effet.
  • Vérifiez si le nombre de répliques a récemment changé ; un remappage est attendu après une mise à l’échelle. Utilisez SELECT hostName() pour déterminer la nouvelle association.
Dernière modification le 26 août 2026