remote, remoteSecure | ClickHouse Docs

表函数 remote 允许即时访问远程服务器，即无需创建 Distributed 表。表函数 remoteSecure 与 remote 相同，但通过安全连接访问。

当目标是普通 db/table 时，这两个函数都可用于 SELECT 和 INSERT 查询。当目标本身是表函数时 (例如 remote('127.0.0.1', numbers(10))) ，该表为只读：没有可供插入的远程表，因此 INSERT 会因 NOT_IMPLEMENTED 异常而被拒绝。

语法

remote(addresses_expr, [db, table, user [, password], sharding_key][, SETTINGS name = value, ...])
remote(addresses_expr, [db.table, user [, password], sharding_key][, SETTINGS name = value, ...])
remote(named_collection[, option=value [,..]][, SETTINGS name = value, ...])
remoteSecure(addresses_expr, [db, table, user [, password], sharding_key][, SETTINGS name = value, ...])
remoteSecure(addresses_expr, [db.table, user [, password], sharding_key][, SETTINGS name = value, ...])
remoteSecure(named_collection[, option=value [,..]][, SETTINGS name = value, ...])

参数

参数	描述
`addresses_expr`	远程服务器地址，或用于生成多个远程服务器地址的表达式。格式：`host` 或 `host:port`。 `host` 可以指定为服务器名称，也可以是 IPv4 或 IPv6 地址。IPv6 地址必须写在 `[]` 中。 `port` 是远程服务器的 TCP 端口。如果省略端口，则表函数 `remote` 使用服务器配置文件中的 tcp_port (默认值为 9000) ，表函数 `remoteSecure` 使用 tcp_port_secure (默认值为 9440) 。对于 IPv6 地址，必须指定端口。如果只指定了参数 `addresses_expr`，则 `db` 和 `table` 默认使用 `system.one`。类型：String。
`db`	数据库名称。类型：String。
`table`	表名称。类型：String。
`user`	用户名。如果未指定，则使用 `default`。类型：String。
`password`	用户密码。如果未指定，则使用空密码。类型：String。
`sharding_key`	分片键，用于支持将数据分布到各个节点。例如：`insert into remote('127.0.0.1:9000,127.0.0.2', db, table, 'default', rand())`。类型：UInt32。
`SETTINGS name = value, ...`	该函数创建的 Distributed 表的设置，例如 `skip_unavailable_shards`。可选。查询中指定的设置优先于它。此子句仅可在表函数内使用；`Remote` 和 `RemoteSecure` 表引擎在引擎定义后接受相同的设置，参见 Remote 和 RemoteSecure 引擎。

参数也可以通过命名集合传递。

返回值

位于远程服务器上的表。

使用

由于表函数 remote 和 remoteSecure 会为每个请求重新建立连接，因此建议改用 Distributed 表。此外，如果设置了主机名，系统会解析这些名称；在使用不同副本时，错误也不会被计入统计。在处理大量查询时，务必提前创建 Distributed 表，不要使用 remote 表函数。

在以下情况下，remote 表函数可能会很有用：

将数据从一个系统一次性迁移到另一个系统
访问特定服务器以进行数据比较、调试和测试，即临时连接。
出于研究目的，在不同 ClickHouse 集群之间执行查询。
手动发起的不频繁分布式请求。
每次都会重新定义服务器集合的分布式请求。

相同的参数也可用于 Remote 和 RemoteSecure 表引擎，以创建持久表而非临时表，参见 Remote 和 RemoteSecure 引擎。唯一的区别在于 SETTINGS 子句：引擎在引擎定义后指定该子句，即 ENGINE = Remote(...) SETTINGS skip_unavailable_shards = 1，而不是将其放在参数中。

地址

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 会使用分布式处理，并将查询发送到所有指定地址 (类似于存放不同数据的分片) 。示例：

example01-01-1,example01-02-1

示例

从远程服务器查询数据：

SELECT * FROM remote('127.0.0.1', db.remote_engine_table) LIMIT 3;

或者使用命名集合：

CREATE NAMED COLLECTION creds AS
        host = '127.0.0.1',
        database = 'db';
SELECT * FROM remote(creds, table='remote_engine_table') LIMIT 3;

向远程服务器上的表中插入数据：

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)
```
show databases
```
```
show tables in imdb
```
从源端系统获取 CREATE TABLE 语句：

  SELECT create_table_query
  FROM system.tables
  WHERE database = 'imdb' AND table = 'actors'

响应

  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 系统上

创建目标数据库：
```
CREATE DATABASE imdb
```

使用源端的 CREATE TABLE 语句创建目标表：

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);

回到源端部署

将数据插入远程系统中新创建的数据库和表。您需要提供主机、端口、用户名、密码、目标端数据库和目标端表。

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 设置中指定的顺序依次遍历副本。生成的地址数量受 table_function_remote_max_addresses 设置的限制。