ClickHouse/docs/ru/sql-reference/table-functions/remote.md

toc_priority	toc_title
40	remote

remote, remoteSecure

Позволяет обратиться к удалённым серверам без создания таблицы типа Distributed. Функция remoteSecure работает аналогично remote, но использует защищенное соединение.

Обе функции могут использоваться в запросах SELECT и INSERT.

Синтаксис

remote('addresses_expr', db, table[, 'user'[, 'password']])
remote('addresses_expr', db.table[, 'user'[, 'password']])
remoteSecure('addresses_expr', db, table[, 'user'[, 'password']])
remoteSecure('addresses_expr', db.table[, 'user'[, 'password']])

Параметры

• addresses_expr — выражение, генерирующее адреса удалённых серверов. Это может быть просто один адрес сервера. Адрес сервера — это host:port или только host.

  Вместо параметра host может быть указано имя сервера или его адрес в формате IPv4 или IPv6. IPv6 адрес указывается в квадратных скобках.

  port — TCP-порт удалённого сервера. Если порт не указан, используется tcp_port из конфигурационного файла сервера, к которому обратились через функцию remote (по умолчанию - 9000), и tcp_port_secure, к которому обратились через функцию remoteSecure (по умолчанию — 9440).

  С IPv6-адресом обязательно нужно указывать порт.

  Тип: 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.

Возвращаемое значение

Набор данных с удаленных серверов.

Использование

Использование табличной функции remote менее оптимально, чем создание таблицы типа Distributed, так как в этом случае соединения с серверами устанавливаются заново при каждом запросе. Если указываются имена серверов, то приходится также выполнять поиск сервера по имени. Кроме того, не ведётся сквозной подсчёт ошибок при работе с разными репликами. При обработке большого количества запросов всегда создавайте таблицу типа Distributed, использовать табличную функцию remote в таких случаях не рекомендуется.

Табличная функция remote может быть полезна в следующих случаях:

• Обращение на конкретный сервер для сравнения данных, отладки и тестирования.
• Запросы между разными кластерами ClickHouse для исследований.
• Нечастые распределённые запросы, задаваемые вручную.
• Распределённые запросы, где набор серверов определяется каждый раз заново.

Адреса

example01-01-1
example01-01-1:9000
localhost
127.0.0.1
[::]:9000
[2a02:6b8:0:1111::11]:9000

Адреса можно указать через запятую. В этом случае ClickHouse обработает запрос как распределённый, т.е. отправит его по всем указанным адресам как на шарды с разными данными. Пример:

example01-01-1,example01-02-1

Часть выражения может быть указана в фигурных скобках. Предыдущий пример может быть записан следующим образом:

example01-0{1,2}-1

В фигурных скобках может быть указан диапазон (неотрицательных целых) чисел через две точки. В этом случае диапазон раскрывается в множество значений, генерирующих адреса шардов. Если запись первого числа начинается с нуля, то значения формируются с таким же выравниванием нулями. Предыдущий пример может быть записан следующим образом:

example01-{01..02}-1

При наличии нескольких пар фигурных скобок генерируется прямое произведение соответствующих множеств.

Адреса или их фрагменты в фигурных скобках можно указать через символ |. В этом случае соответствующие множества адресов понимаются как реплики — запрос будет отправлен на первую живую реплику. При этом реплики перебираются в порядке, согласно текущей настройке load_balancing. В этом примере указаны два шарда, в каждом из которых имеются две реплики:

example01-{01..02}-{1|2}

Количество генерируемых адресов ограничено константой. Сейчас это 1000 адресов.

Примеры

Выборка данных с удаленного сервера:

SELECT * FROM remote('127.0.0.1', db.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;