Direcione solicitações relacionadas à mesma réplica do ClickHouse Cloud para tabelas temporárias, sessões, reutilização de cache e consistência de leitura após gravação
O roteamento com reconhecimento de réplicas (também conhecido como sessões persistentes, roteamento sticky ou afinidade de sessão) direciona solicitaçõ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.
Requer a interface HTTPO roteamento com reconhecimento de réplicas é aplicado na camada de proxy por meio da interface HTTP/HTTPS. O ClickHouse Cloud está migrando o roteamento com reconhecimento de réplicas de session_id para o cabeçalho X-ClickHouse-Replica-Tag. As abas abaixo descrevem ambos os métodos durante o rollout.O roteamento com reconhecimento de réplicas está indisponível atualmente no protocolo nativo (porta nativa, por exemplo, o driver clickhouse-go em seu modo nativo padrão). Clientes do protocolo nativo devem mudar para HTTP e enviar o valor de roteamento em cada solicitação.
Configurando o roteamento com reconhecimento de réplicas
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). Antes de migrar um serviço existente, solicite ao Suporte a confirmação de que o roteamento baseado em header está habilitado para ele. Continue usando session_id até receber a confirmação; X-ClickHouse-Replica-Tag não fornecerá roteamento sticky até que o rollout chegue ao seu serviço. Não é necessário reiniciar.
Para direcionar uma workload a uma réplica específica, envie o header X-ClickHouse-Replica-Tag na interface HTTPS. O proxy usa hash consistente do valor do header; assim, as requests 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 header pode ser qualquer string à sua escolha, como o nome de uma aplicação, o ID de um usuário ou o label da workload. Requests sem o header continuam usando o load balancing normal.Defina o header X-ClickHouse-Replica-Tag em cada request:
Para clickhouse-go (v2), defina Protocol: clickhouse.HTTP e passe o cabeçalho usando a opção de conexão HttpHeaders.
X-ClickHouse-Replica-Tag fornece afinidade com a réplica sem criar uma sessão HTTP do ClickHouse. Solicitações simultâneas podem reutilizar a mesma tag sem encontrar SESSION_IS_LOCKED.
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 workloads 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.
X-ClickHouse-Replica-Tag está substituindo session_id no roteamento com reconhecimento de réplicas. Continue usando session_id até que o Suporte confirme que o roteamento baseado em header está habilitado para seu serviço.
Solicitações simultâneas falham com SESSION_IS_LOCKED
Como session_id cria uma sessão HTTP do ClickHouse, apenas uma consulta pode ser executada em uma mesma sessão por vez.
Após a habilitação do roteamento baseado em header para seu serviço, workloads que precisam apenas de afinidade com réplicas podem migrar para X-ClickHouse-Replica-Tag. Solicitações simultâneas podem compartilhar a mesma tag de réplica.
Se precisar do estado da sessão HTTP do ClickHouse, serialize as solicitações que compartilham um session_id.
Para fixar um workload a uma réplica, envie o parâmetro de consulta session_id na interface HTTPS. O proxy usa hash consistente no valor do parâmetro, portanto, as solicitações que o compartilham são encaminhadas à mesma réplica enquanto o número de réplicas permanecer inalterado. Um valor diferente gera um hash independente e pode ser encaminhado à mesma réplica ou a outra, mas você não escolhe a qual réplica um valor é mapeado.Use o hostname existente do seu serviço. Não são necessários hostnames sticky especiais nem alterações no DNS. O session_id pode ser qualquer string de sua escolha, como o nome de uma aplicação, um ID de usuário ou um rótulo de workload. Solicitações sem session_id continuam usando o balanceamento de carga normal.Defina o parâmetro de consulta session_id em cada solicitação:
Para clickhouse-go (v2), defina Protocol: clickhouse.HTTP e passe session_id como uma configuração. O driver o envia como um parâmetro de consulta na URL.
Consistência de leitura após gravação com session_id
Em um serviço com várias réplicas, uma gravação em uma réplica pode não ficar visível nas outras até que a replicação seja sincronizada. Envie a gravação com um session_id e reutilize o mesmo session_id nas leituras subsequentes. O proxy encaminha ambas para a mesma réplica, permitindo que você leia a própria gravação mesmo enquanto as outras réplicas ainda estão atrasadas. Esse padrão funciona para workloads que gravam e logo em seguida leem os mesmos dados, como aplicações interativas ou jobs de ETL que validam inserts antes de prosseguir.Para garantias mais abrangentes em todas as réplicas, também é possível definir select_sequential_consistency como 1 no ClickHouse Cloud.
Verifique qual réplica foi acessada com session_id
Execute novamente o exemplo SELECT hostName() com o mesmo session_id. Você deverá obter o mesmo hostname enquanto o número de réplicas permanecer inalterado. Um session_id diferente pode ser mapeado para outra réplica.
O roteamento baseado em subdomínio não é mais habilitado em novos serviços. Se você já usa subdomínios sticky, entre em contato com o Suporte para migrar para o método de cabeçalho HTTP.
Como funciona o roteamento baseado em subdomínio legado
Anteriormente, habilitar o roteamento com reconhecimento de réplicas permitia usar um subdomínio curinga sobre o hostname do serviço. Para um serviço com o host name abcxyz123.us-west-2.aws.clickhouse.cloud, qualquer hostname correspondente a *.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud (por exemplo, aaa.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud) era mapeado pelo Envoy, via hash, para uma réplica consistente. O hostname original continuava usando balanceamento de carga LEAST_CONNECTION, o algoritmo de roteamento padrão.
A afinidade muda quando a contagem de réplicas muda
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 com reconhecimento de réplicas não é isolamento de workload
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 método de subdomínio legado não funciona: você precisa adicionar DNS para o padrão de hostname *.sticky.*, e uma configuração incorreta pode desequilibrar a carga entre as réplicas.
O roteamento com reconhecimento de réplicas exige o protocolo HTTP
O roteamento sticky usa como chave um cabeçalho HTTP ou parâmetro de consulta, dependendo do método de roteamento disponível para o seu serviço. O protocolo binário nativo não transporta nenhum desses valores 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 você está usando o método de roteamento disponível para seu serviço: o header X-ClickHouse-Replica-Tag ou o parâmetro de consulta de URL legado session_id.
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.
