remote, remoteSecure

Distributed 테이블을 만들지 않고 원격 서버에 즉석으로(on-the-fly) 접근할 수 있게 해주는 테이블 함수예요. remoteSecure는 remote와 같지만 보안 연결을 사용해요.

출처: 문서

본문

remote 테이블 함수는 Distributed 테이블을 만들지 않고 원격 서버에 즉석으로 접근할 수 있게 해줘요. remoteSecure 테이블 함수는 remote와 같지만 보안 연결을 사용해요.

두 함수 모두 대상이 일반적인 db/table일 때 SELECT와 INSERT 쿼리에서 사용할 수 있어요. 대상 자체가 테이블 함수인 경우(예: remote('127.0.0.1', numbers(10))) 테이블은 읽기 전용이에요: 삽입할 원격 테이블이 없으므로 INSERT는 NOT_IMPLEMENTED 예외로 거부돼요.

문법 (Syntax)

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, ...])

파라미터 (Parameters)

인자	설명
`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 엔진을 참고하세요.

인자는 네임드 컬렉션으로도 전달할 수 있어요.

반환값 (Returned value)

원격 서버에 있는 테이블이에요.

사용법 (Usage)

테이블 함수 remote와 remoteSecure는 요청마다 연결을 다시 맺으므로, Distributed 테이블을 사용하는 것이 좋아요. 또한 호스트네임이 설정되면 이름이 해석되고 다양한 복제본 작업 시 오류가 집계되지 않아요. 많은 수의 쿼리를 처리할 때는 항상 Distributed 테이블을 미리 만들고 remote 테이블 함수를 사용하지 마세요.

remote 테이블 함수는 다음 경우에 유용해요:

한 시스템에서 다른 시스템으로의 일회성 데이터 마이그레이션
데이터 비교, 디버깅, 테스트를 위한 특정 서버 접근, 즉 임시(ad-hoc) 연결
연구 목적의 다양한 ClickHouse 클러스터 간 쿼리
수동으로 만드는 빈번하지 않은 분산 요청
서버 집합이 매번 다시 정의되는 분산 요청

같은 파라미터를 Remote 및 RemoteSecure 테이블 엔진과 함께 사용해 임시 테이블 대신 영구 테이블을 만들 수 있어요. Remote 및 RemoteSecure 엔진을 참고하세요. 유일한 차이는 SETTINGS 절이에요: 엔진은 엔진 정의 뒤에 ENGINE = Remote(...) SETTINGS skip_unavailable_shards = 1처럼 받고, 인자들 사이가 아니에요.

주소 (Addresses)

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

예시 (Examples)

원격 서버에서 데이터 선택:

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

글로빙 (Globbing)

{ } 안의 패턴은 샤드 집합을 생성하고 복제본을 지정하는 데 사용돼요. 여러 쌍의 { }가 있으면 해당 집합들의 직적곱(direct product)이 생성돼요. 다음 패턴 유형이 지원돼요.

{a,b,c} - 대안 문자열 a, b, c 중 아무거나 나타내요. 패턴은 첫 번째 샤드 주소에서 a로, 두 번째 샤드 주소에서 b로 치환되는 식이에요. 예를 들어 example0{1,2}-1은 example01-1과 example02-1을 생성해요.
{N..M} - 숫자 범위예요. 이 패턴은 N부터(M 포함) 증가하는 인덱스로 샤드 주소를 생성해요. 예를 들어 example0{1..2}-1은 example01-1과 example02-1을 생성해요.
{0n..0m} - 앞에 0이 있는 숫자 범위예요. 이 패턴은 인덱스의 앞 0을 보존해요. 예를 들어 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 설정으로 제한돼요.

remote, remoteSecure