Roteamento com reconhecimento de réplicas

O roteamento com reconhecimento de réplicas (também conhecido como sessões persistentes, roteamento sticky ou afinidade de sessão) direciona requisições relacionadas para a mesma réplica do ClickHouse. Use-o quando precisar que tabelas temporárias ou estado de sessão nomeado permaneçam acessíveis entre consultas, quando quiser que consultas relacionadas reutilizem os caches locais da mesma réplica ou quando precisar de consistência de leitura após gravação entre uma gravação e as leituras subsequentes.

É uma abordagem de melhor esforço e não garante isolamento. O proxy mapeia cada valor de roteamento para uma réplica. O mapeamento permanece estável enquanto o número de réplicas não mudar; o escalonamento do serviço pode mapear o valor para outra réplica.

• Seu serviço precisa de 2 ou mais réplicas. Em um serviço com apenas uma réplica, não há nada ao que se vincular.
• Disponível no Enterprise por padrão quando o recurso estiver em GA.
• Compatível com os serviços padrão do ClickHouse Cloud. O BYOC ainda não é compatível.

Abra um ticket de suporte e solicite a habilitação do roteamento sticky de réplicas via HTTP. Inclua o ID do seu serviço e o motivo da necessidade (tabelas temporárias, estado da sessão, reutilização de cache ou consistência de leitura após gravação). Não é necessário reiniciar.

Para direcionar uma carga de trabalho a uma réplica específica, envie o cabeçalho X-ClickHouse-Replica-Tag na interface HTTPS. O proxy usa hash consistente do valor do cabeçalho; assim, as requisições que compartilham esse valor são direcionadas à mesma réplica enquanto o número de réplicas permanecer inalterado. Um valor diferente recebe um hash independente e pode ser direcionado à mesma réplica ou a outra, mas você não escolhe a qual réplica um valor é mapeado.

Use o hostname do service existente. Não são necessários hostnames sticky especiais nem alterações de DNS. O valor do cabeçalho pode ser qualquer string à sua escolha, como o nome de uma aplicação, o ID de um usuário ou o label da carga de trabalho. Requisições sem o cabeçalho continuam usando o load balancing normal.

Defina o cabeçalho X-ClickHouse-Replica-Tag em cada requisição:

echo 'SELECT hostName()' | curl \
  -H 'X-ClickHouse-Replica-Tag: my-workload-1' \
  -H 'X-ClickHouse-User: default' \
  -H 'X-ClickHouse-Key: <password>' \
  'https://<host>:8443/' -d @-

Para clickhouse-go (v2), defina Protocol: clickhouse.HTTP e passe o cabeçalho usando a opção de conexão HttpHeaders.

Em um serviço com várias réplicas, uma gravação em uma réplica pode não ficar visível nas demais até que a replicação seja concluída. Envie a gravação com um cabeçalho X-ClickHouse-Replica-Tag e reutilize o mesmo valor do cabeçalho nas leituras subsequentes. O proxy encaminha ambas para a mesma réplica, para que você leia sua própria gravação mesmo enquanto as outras réplicas ainda estiverem atrasadas. Esse padrão é adequado para cargas de trabalho que gravam e, em seguida, leem imediatamente os mesmos dados, como aplicações interativas ou jobs de ETL que validam inserts antes de continuar.

Para obter garantias mais amplas em todas as réplicas, também é possível definir select_sequential_consistency como 1 no ClickHouse Cloud.

Execute novamente o exemplo SELECT hostName() com o mesmo valor de X-ClickHouse-Replica-Tag. Você deverá obter o mesmo hostname enquanto o número de réplicas permanecer inalterado. Um valor de cabeçalho diferente pode ser mapeado para outra réplica.

O aumento ou a redução de escala altera o hash ring de roteamento. Requisições que compartilham o mesmo valor de roteamento podem, então, ser encaminhadas para uma réplica diferente. Se você depende de tabelas temporárias ou de configurações da sessão, esteja preparado para recriá-las após um remapeamento.

O roteamento sticky controla apenas qual réplica atende a uma solicitação. Essa réplica ainda pode atender outro tráfego. Para processamento dedicado, use compute-compute separation.

O roteamento baseado em HTTP funciona com rede privada no hostname padrão do seu serviço. Nenhuma entrada DNS adicional é necessária.

O roteamento sticky usa como chave o cabeçalho HTTP X-ClickHouse-Replica-Tag. O protocolo binário nativo não transporta esse valor para que o proxy HTTP possa aplicar hash e, por isso, o roteamento com reconhecimento de réplicas não está disponível no protocolo nativo. Clientes do protocolo nativo precisam mover a carga de trabalho relevante para a interface HTTP para usar esse recurso.

As consultas continuam sendo direcionadas a réplicas diferentes com o mesmo valor de roteamento

• Confirme que cada solicitação inclui o cabeçalho X-ClickHouse-Replica-Tag.
• Confirme que cada solicitação usa exatamente o mesmo valor de roteamento.
• Aguarde um pouco após a ativação. Pode levar menos de um minuto para surtir efeito.
• Verifique se o número de réplicas mudou recentemente; é esperado que haja remapeamento após o escalonamento. Use SELECT hostName() para descobrir o novo mapeamento.