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

> A função de tabela `remote` permite acessar servidores remotos dinamicamente, ou seja, sem criar uma tabela [Distributed](/reference/engines/table-engines/special/distributed). A função de tabela `remoteSecure` é igual à `remote`, mas por meio de uma conexão segura.

# remote, remoteSecure

A função de tabela `remote` permite acessar servidores remotos dinamicamente, ou seja, sem criar uma tabela [Distributed](/pt-BR/reference/engines/table-engines/special/distributed). A função de tabela `remoteSecure` é igual à `remote`, mas por meio de uma conexão segura.

Ambas as funções podem ser usadas em consultas `SELECT` e `INSERT`.

<div id="syntax">
  ## Sintaxe
</div>

```sql theme={null}
remote(addresses_expr, [db, table, user [, password], sharding_key])
remote(addresses_expr, [db.table, user [, password], sharding_key])
remote(named_collection[, option=value [,..]])
remoteSecure(addresses_expr, [db, table, user [, password], sharding_key])
remoteSecure(addresses_expr, [db.table, user [, password], sharding_key])
remoteSecure(named_collection[, option=value [,..]])
```

<div id="parameters">
  ## Parâmetros
</div>

| Argumento        | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `addresses_expr` | Um endereço de servidor remoto ou uma expressão que gera vários endereços de servidores remotos. Formato: `host` ou `host:port`.<br /><br />    O `host` pode ser especificado como um nome de servidor ou como um endereço IPv4 ou IPv6. Um endereço IPv6 deve ser especificado entre `[]`.<br /><br />    A `port` é a porta TCP no servidor remoto. Se a porta for omitida, será usado [tcp\_port](/pt-BR/reference/settings/server-settings/settings#tcp_port) do arquivo de configuração do servidor para a função de tabela `remote` (por padrão, 9000) e [tcp\_port\_secure](/pt-BR/reference/settings/server-settings/settings#tcp_port_secure) para a função de tabela `remoteSecure` (por padrão, 9440).<br /><br />    Para endereços IPv6, a porta é obrigatória.<br /><br />    Se apenas o parâmetro `addresses_expr` for especificado, `db` e `table` usarão `system.one` por padrão.<br /><br />    Tipo: [String](/pt-BR/reference/data-types/string). |
| `db`             | Nome do banco de dados. Tipo: [String](/pt-BR/reference/data-types/string).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `table`          | Nome da tabela. Tipo: [String](/pt-BR/reference/data-types/string).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `user`           | Nome de usuário. Se não for especificado, `default` será usado. Tipo: [String](/pt-BR/reference/data-types/string).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `password`       | Senha do usuário. Se não for especificado, será usada uma senha vazia. Tipo: [String](/pt-BR/reference/data-types/string).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `sharding_key`   | Chave de sharding para dar suporte à distribuição de dados entre nós. Por exemplo: `insert into remote('127.0.0.1:9000,127.0.0.2', db, table, 'default', rand())`. Tipo: [UInt32](/pt-BR/reference/data-types/int-uint).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

Os argumentos também podem ser passados por meio de [coleções nomeadas](/pt-BR/concepts/features/configuration/server-config/named-collections).

<div id="returned-value">
  ## Valor retornado
</div>

Uma tabela localizada em um servidor remoto.

<div id="usage">
  ## Uso
</div>

Como as funções de tabela `remote` e `remoteSecure` restabelecem a conexão a cada solicitação, recomenda-se usar uma tabela `Distributed` em vez delas. Além disso, se os hostnames estiverem definidos, os nomes serão resolvidos, e os erros não serão contabilizados ao trabalhar com várias réplicas. Ao processar um grande número de consultas, sempre crie a tabela `Distributed` com antecedência e não use a função de tabela `remote`.

A função de tabela `remote` pode ser útil nos seguintes casos:

* Migração pontual de dados de um sistema para outro
* Acesso a um servidor específico para comparação de dados, depuração e testes, ou seja, conexões ad hoc.
* Consultas entre vários clusters do ClickHouse para fins de pesquisa.
* Solicitações distribuídas pouco frequentes feitas manualmente.
* Solicitações distribuídas em que o conjunto de servidores é redefinido a cada vez.

<div id="addresses">
  ### Endereços
</div>

```text theme={null}
example01-01-1
example01-01-1:9440
example01-01-1:9000
localhost
127.0.0.1
[::]:9440
[::]:9000
[2a02:6b8:0:1111::11]:9000
```

Vários endereços podem ser informados separados por vírgulas. Nesse caso, o ClickHouse usará processamento distribuído e enviará a consulta para todos os endereços especificados (como shards com dados diferentes). Exemplo:

```text theme={null}
example01-01-1,example01-02-1
```

<div id="examples">
  ## Exemplos
</div>

<div id="selecting-data-from-a-remote-server">
  ### Selecionando dados de um servidor remoto:
</div>

```sql theme={null}
SELECT * FROM remote('127.0.0.1', db.remote_engine_table) LIMIT 3;
```

Ou usando [coleções nomeadas](/pt-BR/concepts/features/configuration/server-config/named-collections):

```sql theme={null}
CREATE NAMED COLLECTION creds AS
        host = '127.0.0.1',
        database = 'db';
SELECT * FROM remote(creds, table='remote_engine_table') LIMIT 3;
```

<div id="inserting-data-into-a-table-on-a-remote-server">
  ### Inserindo dados em uma tabela em um servidor remoto:
</div>

```sql theme={null}
CREATE TABLE remote_table (name String, value UInt32) ENGINE=Memory;
INSERT INTO FUNCTION remote('127.0.0.1', currentDatabase(), 'remote_table') VALUES ('test', 42);
SELECT * FROM remote_table;
```

<div id="migration-of-tables-from-one-system-to-another">
  ### Migração de tabelas de um sistema para outro:
</div>

Este exemplo usa uma tabela de um conjunto de dados de amostra. O banco de dados é `imdb`, e a tabela é `actors`.

<div id="on-the-source-clickhouse-system-the-system-that-currently-hosts-the-data">
  #### No sistema ClickHouse de origem (o sistema que hospeda os dados atualmente)
</div>

* Verifique o banco de dados de origem e o nome da tabela (`imdb.actors`)

  ```sql theme={null}
  show databases
  ```

  ```sql theme={null}
  show tables in imdb
  ```

* Obtenha a instrução CREATE TABLE na origem:

```sql theme={null}
  SELECT create_table_query
  FROM system.tables
  WHERE database = 'imdb' AND table = 'actors'
```

Resposta

```sql theme={null}
  CREATE TABLE imdb.actors (`id` UInt32,
                            `first_name` String,
                            `last_name` String,
                            `gender` FixedString(1))
                  ENGINE = MergeTree
                  ORDER BY (id, first_name, last_name, gender);
```

<div id="on-the-destination-clickhouse-system">
  #### No sistema de destino do ClickHouse
</div>

* Crie o banco de dados de destino:

  ```sql theme={null}
  CREATE DATABASE imdb
  ```

* Usando a instrução CREATE TABLE da origem, crie a tabela no destino:

  ```sql theme={null}
  CREATE TABLE imdb.actors (`id` UInt32,
                            `first_name` String,
                            `last_name` String,
                            `gender` FixedString(1))
                  ENGINE = MergeTree
                  ORDER BY (id, first_name, last_name, gender);
  ```

<div id="back-on-the-source-deployment">
  #### De volta à implantação de origem
</div>

Insira dados no novo banco de dados e na nova tabela criados no sistema remoto. Você precisará do host, da porta, do nome de usuário, da senha, do banco de dados de destino e da tabela de destino.

```sql theme={null}
INSERT INTO FUNCTION
remoteSecure('remote.clickhouse.cloud:9440', 'imdb.actors', 'USER', 'PASSWORD')
SELECT * from imdb.actors
```

<div id="globs-in-addresses">
  ## Globbing
</div>

Padrões em `{ }` são usados para gerar um conjunto de shards e para especificar réplicas. Se houver vários pares de `{ }`, o produto cartesiano dos conjuntos correspondentes será gerado.

Os seguintes tipos de padrão são suportados.

* `{a,b,c}` - Representa qualquer uma das strings alternativas `a`, `b` ou `c`. O padrão é substituído por `a` no endereço do primeiro shard, por `b` no endereço do segundo shard e assim por diante. Por exemplo, `example0{1,2}-1` gera os endereços `example01-1` e `example02-1`.
* `{N..M}` - Um intervalo de números. Esse padrão gera endereços de shard com índices crescentes de `N` até `M` (inclusive). Por exemplo, `example0{1..2}-1` gera `example01-1` e `example02-1`.
* `{0n..0m}` - Um intervalo de números com zeros à esquerda. Esse padrão preserva os zeros à esquerda nos índices. Por exemplo, `example{01..03}-1` gera `example01-1`, `example02-1` e `example03-1`.
* `{a|b}` - Qualquer número de variantes separadas por `|`. O padrão especifica réplicas. Por exemplo, `example01-{1|2}` gera as réplicas `example01-1` e `example01-2`.

A consulta será enviada para a primeira réplica saudável. No entanto, para `remote`, as réplicas são iteradas na ordem atualmente definida na configuração [load\_balancing](/pt-BR/reference/settings/session-settings#load_balancing).
O número de endereços gerados é limitado pela configuração [table\_function\_remote\_max\_addresses](/pt-BR/reference/settings/session-settings#table_function_remote_max_addresses).