> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Roteamento com reconhecimento de réplicas

> Direcione requisiçõ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

export const EnterprisePlanFeatureBadge = ({feature = 'Este recurso', support = false, linking_verb_are = false}) => {
  return <div className="enterprisePlanFeatureContainer">
            <div className="enterprisePlanFeatureBadge">
                Recurso do plano Enterprise
            </div>
            <div>
                <p>{feature} {linking_verb_are ? 'estão disponíveis' : 'está disponível'} no plano Enterprise. {support ? `Entre em contato com o suporte para habilitar este recurso.` : 'Para fazer o upgrade, acesse a página de planos no Cloud Console.'}</p>
            </div>
        </div>;
};

export const PrivatePreviewBadge = () => {
  return <div className="privatePreviewBadge">
            <div className="privatePreviewIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M5.33301 6.66667V4.66667V4.66667C5.33301 3.194 6.52701 2 7.99967 2V2C9.47234 2 10.6663 3.194 10.6663 4.66667V4.66667V6.66667" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path d="M8.00033 9.33337V11.3334" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path fillRule="evenodd" clipRule="evenodd" d="M11.333 14H4.66634C3.92967 14 3.33301 13.4033 3.33301 12.6666V7.99996C3.33301 7.26329 3.92967 6.66663 4.66634 6.66663H11.333C12.0697 6.66663 12.6663 7.26329 12.6663 7.99996V12.6666C12.6663 13.4033 12.0697 14 11.333 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'Em prévia privada no ClickHouse Cloud'}
        </div>;
};

<PrivatePreviewBadge />

<EnterprisePlanFeatureBadge feature="Roteamento com reconhecimento de réplicas" support="true" />

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](/pt-BR/reference/statements/create/table/temporary-table) ou [estado de sessão nomeado](/pt-BR/concepts/features/interfaces/http#using-clickhouse-sessions-in-the-http-protocol) 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](#read-after-write-consistency) 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.

<Warning>
  **Requer a interface HTTP**

  O roteamento com reconhecimento de réplicas é aplicado na camada de proxy por meio da [interface HTTP/HTTPS](/pt-BR/concepts/features/interfaces/http) usando o cabeçalho `X-ClickHouse-Replica-Tag`.

  O roteamento com reconhecimento de réplicas está **indisponível atualmente no protocolo nativo** (porta nativa, por exemplo, o driver [clickhouse-go](/pt-BR/integrations/language-clients/go/index) em seu modo nativo padrão). Clientes do protocolo nativo devem mudar para HTTP e enviar o valor de roteamento em cada requisição.
</Warning>

<div id="prerequisites">
  ## Pré-requisitos
</div>

* 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](/pt-BR/products/cloud/guides/infrastructure/deployment-options/byoc/overview) ainda não é compatível.

<div id="configuring-replica-aware-routing">
  ## Configurando o roteamento com reconhecimento de réplicas
</div>

Abra um ticket de [suporte](https://clickhouse.com/support/program) 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.

<div id="http-based-routing">
  ## Roteamento baseado em HTTP
</div>

Para direcionar uma carga de trabalho a uma réplica específica, envie o cabeçalho `X-ClickHouse-Replica-Tag` na [interface HTTPS](/pt-BR/concepts/features/interfaces/http). 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:

```bash theme={null}
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`](/pt-BR/integrations/language-clients/go/configuration#connection-settings).

<Info>
  `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`.
</Info>

<div id="read-after-write-consistency">
  ### Consistência de leitura após gravação
</div>

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`](/pt-BR/reference/settings/session-settings#select_sequential_consistency) como `1` no ClickHouse Cloud.

<div id="check-which-replica">
  ### Verifique qual réplica foi acessada
</div>

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.

<div id="limitations-of-replica-aware-routing">
  ## Limitações do roteamento com reconhecimento de réplicas
</div>

<div id="replica-aware-routing-does-not-guarantee-isolation">
  ### A afinidade muda quando a contagem de réplicas muda
</div>

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.

<div id="not-workload-isolation">
  ### O roteamento com reconhecimento de réplicas não é isolamento de workload
</div>

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](/pt-BR/products/cloud/features/infrastructure/warehouses).

<div id="private-networking">
  ### Rede privada
</div>

O roteamento baseado em HTTP funciona com [rede privada](/pt-BR/products/cloud/guides/security/connectivity/private-networking) no hostname padrão do seu serviço. Nenhuma entrada DNS adicional é necessária.

<div id="replica-aware-routing-requires-http">
  ### O roteamento com reconhecimento de réplicas exige o protocolo HTTP
</div>

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.

<div id="troubleshooting">
  ## Solução de problemas
</div>

**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.