> ## 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.
> 表函数 `remote` 允许即时访问远程服务器，即无需创建 [Distributed](/reference/engines/table-engines/special/distributed) 表。表函数 `remoteSecure` 与 `remote` 相同，但通过安全连接访问。
# remote, remoteSecure
表函数 `remote` 允许即时访问远程服务器，即无需创建 [Distributed](/zh/reference/engines/table-engines/special/distributed) 表。表函数 `remoteSecure` 与 `remote` 相同，但通过安全连接访问。
这两个函数都可用于 `SELECT` 和 `INSERT` 查询。
## 语法
```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 [,..]])
```
## 参数
| 参数 | 描述 |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `addresses_expr` | 远程服务器地址，或用于生成多个远程服务器地址的表达式。格式：`host` 或 `host:port`。
`host` 可以指定为服务器名称，也可以是 IPv4 或 IPv6 地址。IPv6 地址必须写在 `[]` 中。
`port` 是远程服务器的 TCP 端口。如果省略端口，则表函数 `remote` 使用服务器配置文件中的 [tcp\_port](/zh/reference/settings/server-settings/settings#tcp_port) (默认值为 9000) ，表函数 `remoteSecure` 使用 [tcp\_port\_secure](/zh/reference/settings/server-settings/settings#tcp_port_secure) (默认值为 9440) 。
对于 IPv6 地址，必须指定端口。
如果只指定了参数 `addresses_expr`，则 `db` 和 `table` 默认使用 `system.one`。
类型：[String](/zh/reference/data-types/string)。 |
| `db` | 数据库名称。类型：[String](/zh/reference/data-types/string)。 |
| `table` | 表名称。类型：[String](/zh/reference/data-types/string)。 |
| `user` | 用户名。如果未指定，则使用 `default`。类型：[String](/zh/reference/data-types/string)。 |
| `password` | 用户密码。如果未指定，则使用空密码。类型：[String](/zh/reference/data-types/string)。 |
| `sharding_key` | 分片键，用于支持将数据分布到各个节点。例如：`insert into remote('127.0.0.1:9000,127.0.0.2', db, table, 'default', rand())`。类型：[UInt32](/zh/reference/data-types/int-uint)。 |
参数也可以通过 [命名集合](/zh/concepts/features/configuration/server-config/named-collections) 传递。
## 返回值
位于远程服务器上的表。
## 使用
由于表函数 `remote` 和 `remoteSecure` 会为每个请求重新建立连接，因此建议改用 `Distributed` 表。此外，如果设置了主机名，系统会解析这些名称；在使用不同副本时，错误也不会被计入统计。在处理大量查询时，务必提前创建 `Distributed` 表，不要使用 `remote` 表函数。
在以下情况下，`remote` 表函数可能会很有用：
* 将数据从一个系统一次性迁移到另一个系统
* 访问特定服务器以进行数据比较、调试和测试，即临时连接。
* 出于研究目的，在不同 ClickHouse 集群之间执行查询。
* 手动发起的不频繁分布式请求。
* 每次都会重新定义服务器集合的分布式请求。
### 地址
```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
```
多个地址可用逗号分隔。在这种情况下，ClickHouse 会使用分布式处理，并将查询发送到所有指定地址 (类似于存放不同数据的分片) 。示例：
```text theme={null}
example01-01-1,example01-02-1
```
## 示例
### 从远程服务器查询数据：
```sql theme={null}
SELECT * FROM remote('127.0.0.1', db.remote_engine_table) LIMIT 3;
```
或者使用[命名集合](/zh/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;
```
### 向远程服务器上的表中插入数据：
```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;
```
### 将表从一个系统迁移到另一个系统：
本示例使用样本数据集中的一个表。数据库为 `imdb`，表为 `actors`。
#### 在源端 ClickHouse 系统上 (即当前承载数据的系统)
* 确认源端数据库和表名 (`imdb.actors`)
```sql theme={null}
show databases
```
```sql theme={null}
show tables in imdb
```
* 从源端系统获取 CREATE TABLE 语句：
```sql theme={null}
SELECT create_table_query
FROM system.tables
WHERE database = 'imdb' AND table = 'actors'
```
响应
```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);
```
#### 在目标端 ClickHouse 系统上
* 创建目标数据库：
```sql theme={null}
CREATE DATABASE imdb
```
* 使用源端的 CREATE TABLE 语句创建目标表：
```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);
```
#### 回到源端部署
将数据插入远程系统中新创建的数据库和表。您需要提供主机、端口、用户名、密码、目标端数据库和目标端表。
```sql theme={null}
INSERT INTO FUNCTION
remoteSecure('remote.clickhouse.cloud:9440', 'imdb.actors', 'USER', 'PASSWORD')
SELECT * from imdb.actors
```
## 通配符展开
`{ }` 中的模式用于生成一组分片并指定副本。如果存在多对 `{ }`，则会生成相应集合的笛卡尔积。
支持以下模式类型。
* `{a,b,c}` - 表示备选字符串 `a`、`b` 或 `c` 中的任意一个。该模式在第一个分片地址中会被替换为 `a`，在第二个分片地址中会被替换为 `b`，依此类推。例如，`example0{1,2}-1` 会生成地址 `example01-1` 和 `example02-1`。
* `{N..M}` - 数字范围。该模式会生成索引从 `N` 递增到 `M` (含 `M`) 的分片地址。例如，`example0{1..2}-1` 会生成 `example01-1` 和 `example02-1`。
* `{0n..0m}` - 带前导零的数字范围。该模式会保留索引中的前导零。例如，`example{01..03}-1` 会生成 `example01-1`、`example02-1` 和 `example03-1`。
* `{a|b}` - 由 `|` 分隔的任意数量的变体。该模式用于指定副本。例如，`example01-{1|2}` 会生成副本 `example01-1` 和 `example01-2`。
查询将发送到第一个健康的副本。不过，对于 `remote`，会按照当前 [load\_balancing](/zh/reference/settings/session-settings#load_balancing) 设置中指定的顺序依次遍历副本。
生成的地址数量受 [table\_function\_remote\_max\_addresses](/zh/reference/settings/session-settings#table_function_remote_max_addresses) 设置的限制。