> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Roteamento com reconhecimento de réplicas

> 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

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 />

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](/docs/pt-BR/reference/statements/create/table/temporary-table) ou [estado de sessão nomeado](/docs/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](/docs/pt-BR/concepts/features/interfaces/http). 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](/docs/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 solicitaçã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](/docs/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). 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.

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

<Tabs>
  <Tab title="X-ClickHouse-Replica-Tag (preferido)">
    Para direcionar uma workload a uma réplica específica, envie o header `X-ClickHouse-Replica-Tag` na [interface HTTPS](/docs/pt-BR/concepts/features/interfaces/http). 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:

    ```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`](/docs/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>

    ### Consistência de leitura após gravação

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

    ### Verifique qual réplica foi acessada

    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.
  </Tab>

  <Tab title="session_id (legado)">
    <Warning>
      `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.
    </Warning>

    **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](/docs/pt-BR/concepts/features/interfaces/http). 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:

    ```bash theme={null}
    echo 'SELECT hostName()' | curl \
      -H 'X-ClickHouse-User: default' \
      -H 'X-ClickHouse-Key: <password>' \
      'https://<host>:8443/?session_id=my-workload-1' -d @-
    ```

    Para clickhouse-go (v2), defina `Protocol: clickhouse.HTTP` e passe `session_id` como uma [configuração](/docs/pt-BR/integrations/language-clients/go/database-sql-api#sessions). 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`](/docs/pt-BR/reference/settings/session-settings#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.
  </Tab>
</Tabs>

<div id="subdomain-based-routing-deprecated">
  ## Roteamento baseado em subdomínio legado
</div>

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](https://clickhouse.com/support/program) para migrar para o [método de cabeçalho HTTP](#http-based-routing).

<Accordion title="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.
</Accordion>

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

<div id="replica-aware-routing-does-not-work-out-of-the-box-with-private-link">
  ### Private Link e o método de subdomínio legado
</div>

O roteamento baseado em HTTP funciona com [rede privada](/docs/pt-BR/products/cloud/guides/security/connectivity/private-networking) 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.

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

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