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

> Documentação sobre a descoberta de clusters no ClickHouse

# Descoberta de clusters

<div id="overview">
  ## Visão geral
</div>

O recurso Cluster Discovery do ClickHouse simplifica a configuração do cluster, permitindo que os nós se descubram e se registrem automaticamente, sem precisar ser definidos explicitamente nos arquivos de configuração. Isso é especialmente útil quando a definição manual de cada nó se torna trabalhosa.

<Note>
  Cluster Discovery é um recurso experimental e pode ser alterado ou removido em versões futuras.
  Para habilitá-lo, inclua a configuração `allow_experimental_cluster_discovery` no seu arquivo de configuração:

  ```xml theme={null}
  <clickhouse>
      <!-- ... -->
      <allow_experimental_cluster_discovery>1</allow_experimental_cluster_discovery>
      <!-- ... -->
  </clickhouse>
  ```
</Note>

<div id="remote-servers-configuration">
  ## Configuração dos servidores remotos
</div>

<div id="traditional-manual-configuration">
  ### Configuração manual tradicional
</div>

Tradicionalmente, no ClickHouse, era necessário especificar manualmente, na configuração, cada shard e réplica do cluster:

```xml theme={null}
<remote_servers>
    <cluster_name>
        <shard>
            <replica>
                <host>node1</host>
                <port>9000</port>
            </replica>
            <replica>
                <host>node2</host>
                <port>9000</port>
            </replica>
        </shard>
        <shard>
            <replica>
                <host>node3</host>
                <port>9000</port>
            </replica>
            <replica>
                <host>node4</host>
                <port>9000</port>
            </replica>
        </shard>
    </cluster_name>
</remote_servers>

```

<div id="using-cluster-discovery">
  ### Usando o Cluster Discovery
</div>

Com o Cluster Discovery, em vez de definir explicitamente cada nó, basta especificar um caminho no ZooKeeper. Todos os nós que se registrarem nesse caminho no ZooKeeper serão descobertos automaticamente e adicionados ao cluster.

```xml theme={null}
<remote_servers>
    <cluster_name>
        <discovery>
            <path>/clickhouse/discovery/cluster_name</path>

            <!-- # Parâmetros de configuração opcionais: -->

            <!-- ## Credenciais de autenticação para acessar todos os outros nós no cluster: -->
            <!-- <user>user1</user> -->
            <!-- <password>pass123</password> -->
            <!-- ### Como alternativa à senha, um Secret entre servidores pode ser usado: -->
            <!-- <secret>secret123</secret> -->

            <!-- ## Shard do nó atual (veja abaixo): -->
            <!-- <shard>1</shard> -->

            <!-- ## Modo observador (veja abaixo): -->
            <!-- <observer/> -->
        </discovery>
    </cluster_name>
</remote_servers>
```

Se quiser especificar um número de `shard` para um nó específico, você pode incluir a tag `<shard>` na seção `<discovery>`:

para `node1` e `node2`:

```xml theme={null}
<discovery>
    <path>/clickhouse/discovery/cluster_name</path>
    <shard>1</shard>
</discovery>
```

para `node3` e `node4`:

```xml theme={null}
<discovery>
    <path>/clickhouse/discovery/cluster_name</path>
    <shard>2</shard>
</discovery>
```

<div id="observer-mode">
  ### Modo observador
</div>

Os nós configurados no modo observador não se registrarão como réplicas.
Eles apenas observarão e detectarão outras réplicas ativas no cluster, sem participar ativamente.
Para habilitar o modo observador, inclua a tag `<observer/>` na seção `<discovery>`:

```xml theme={null}
<discovery>
    <path>/clickhouse/discovery/cluster_name</path>
    <observer/>
</discovery>
```

<div id="discovery-of-clusters">
  ### Descoberta de clusters
</div>

Às vezes, pode ser necessário adicionar e remover não apenas hosts em clusters, mas também os próprios clusters. Você pode usar o nó `<multicluster_root_path>` com o caminho raiz de vários clusters:

```xml theme={null}
<remote_servers>
    <some_unused_name>
        <discovery>
            <multicluster_root_path>/clickhouse/discovery</multicluster_root_path>
            <observer/>
        </discovery>
    </some_unused_name>
</remote_servers>
```

Neste caso, quando outro host se registra com o caminho `/clickhouse/discovery/some_new_cluster`, um cluster chamado `some_new_cluster` será adicionado.

Você pode usar os dois recursos simultaneamente; o host pode se registrar no cluster `my_cluster` e descobrir outros clusters:

```xml theme={null}
<remote_servers>
    <my_cluster>
        <discovery>
            <path>/clickhouse/discovery/my_cluster</path>
        </discovery>
    </my_cluster>
    <some_unused_name>
        <discovery>
            <multicluster_root_path>/clickhouse/discovery</multicluster_root_path>
            <observer/>
        </discovery>
    </some_unused_name>
</remote_servers>
```

Limitações:

* Você não pode usar `<path>` e `<multicluster_root_path>` na mesma subárvore de `remote_servers`.
* `<multicluster_root_path>` só pode ser usado com `<observer/>`.
* A última parte do path no Keeper é usada como nome do cluster, enquanto, no registro, o nome é obtido da tag XML.

<div id="use-cases-and-limitations">
  ## Casos de uso e limitações
</div>

À medida que nós são adicionados ou removidos do path do ZooKeeper especificado, eles são automaticamente descobertos ou removidos do cluster, sem a necessidade de alterações na configuração ou de reinicializar o servidor.

No entanto, as alterações afetam apenas a configuração do cluster, não os dados nem os bancos de dados e as tabelas existentes.

Considere o exemplo a seguir com um cluster de 3 nós:

```xml theme={null}
<remote_servers>
    <default>
        <discovery>
            <path>/clickhouse/discovery/default_cluster</path>
        </discovery>
    </default>
</remote_servers>
```

```sql theme={null}
SELECT * EXCEPT (default_database, errors_count, slowdowns_count, estimated_recovery_time, database_shard_name, database_replica_name)
FROM system.clusters WHERE cluster = 'default';

┌─cluster─┬─shard_num─┬─shard_weight─┬─replica_num─┬─host_name────┬─host_address─┬─port─┬─is_local─┬─user─┬─is_active─┐
│ default │         1 │            1 │           1 │ 92d3c04025e8 │ 172.26.0.5   │ 9000 │        0 │      │      ᴺᵁᴸᴸ │
│ default │         1 │            1 │           2 │ a6a68731c21b │ 172.26.0.4   │ 9000 │        1 │      │      ᴺᵁᴸᴸ │
│ default │         1 │            1 │           3 │ 8e62b9cb17a1 │ 172.26.0.2   │ 9000 │        0 │      │      ᴺᵁᴸᴸ │
└─────────┴───────────┴──────────────┴─────────────┴──────────────┴──────────────┴──────┴──────────┴──────┴───────────┘
```

```sql theme={null}
CREATE TABLE event_table ON CLUSTER default (event_time DateTime, value String)
ENGINE = ReplicatedMergeTree('/clickhouse/tables/event_table', '{replica}')
ORDER BY event_time PARTITION BY toYYYYMM(event_time);

INSERT INTO event_table ...
```

Em seguida, adicionamos um novo nó ao cluster, iniciando-o com a mesma entrada na seção `remote_servers` de um arquivo de configuração:

```response theme={null}
┌─cluster─┬─shard_num─┬─shard_weight─┬─replica_num─┬─host_name────┬─host_address─┬─port─┬─is_local─┬─user─┬─is_active─┐
│ default │         1 │            1 │           1 │ 92d3c04025e8 │ 172.26.0.5   │ 9000 │        0 │      │      ᴺᵁᴸᴸ │
│ default │         1 │            1 │           2 │ a6a68731c21b │ 172.26.0.4   │ 9000 │        1 │      │      ᴺᵁᴸᴸ │
│ default │         1 │            1 │           3 │ 8e62b9cb17a1 │ 172.26.0.2   │ 9000 │        0 │      │      ᴺᵁᴸᴸ │
│ default │         1 │            1 │           4 │ b0df3669b81f │ 172.26.0.6   │ 9000 │        0 │      │      ᴺᵁᴸᴸ │
└─────────┴───────────┴──────────────┴─────────────┴──────────────┴──────────────┴──────┴──────────┴──────┴───────────┘
```

O quarto nó participa do cluster, mas a tabela `event_table` ainda existe apenas nos três primeiros nós:

```sql theme={null}
SELECT hostname(), database, table FROM clusterAllReplicas(default, system.tables) WHERE table = 'event_table' FORMAT PrettyCompactMonoBlock

┌─hostname()───┬─database─┬─table───────┐
│ a6a68731c21b │ default  │ event_table │
│ 92d3c04025e8 │ default  │ event_table │
│ 8e62b9cb17a1 │ default  │ event_table │
└──────────────┴──────────┴─────────────┘
```

Se você precisar que as tabelas sejam replicadas em todos os nós, poderá usar o mecanismo de banco de dados [Replicated](/docs/pt-BR/reference/engines/database-engines/replicated) como alternativa à Cluster Discovery.