메인 콘텐츠로 건너뛰기
테이블 함수 remote를 사용하면 분산 테이블을 생성하지 않고도 필요할 때 바로 원격 서버에 액세스할 수 있습니다. 테이블 함수 remoteSecure는 remote와 동일하지만 보안 연결을 사용합니다. 두 함수 모두 SELECT 및 INSERT 쿼리에서 사용할 수 있습니다.

​
구문

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(기본값 9000)를 사용하고, 테이블 함수 remoteSecure에는 tcp_port_secure(기본값 9440)를 사용합니다.

IPv6 주소에는 포트 지정이 필요합니다.

addresses_expr 매개변수만 지정하면 db와 table에는 기본적으로 system.one이 사용됩니다.

유형: String.
dbDB 이름입니다. 유형: 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 및 remoteSecure는 각 요청마다 연결을 다시 설정하므로, 대신 분산 테이블을 사용하는 것이 좋습니다. 또한 호스트명이 설정되어 있으면 이름 확인(name resolution)이 수행되며, 여러 레플리카로 작업할 때 발생하는 오류는 집계되지 않습니다. 많은 수의 쿼리를 처리할 때는 항상 분산 테이블을 미리 생성하고, remote 테이블 함수는 사용하지 마십시오. remote 테이블 함수는 다음과 같은 경우에 유용할 수 있습니다.
  • 한 시스템에서 다른 시스템으로 데이터를 한 번만 마이그레이션하는 경우
  • 데이터 비교, 디버깅, 테스트를 위해 특정 서버에 액세스하는 경우, 즉 임시 연결
  • 연구 목적으로 여러 ClickHouse 클러스터 간에 수행하는 쿼리
  • 수동으로 수행하는 드문 분산 요청
  • 서버 집합을 매번 다시 정의하는 분산 요청

​
주소

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;

​
한 시스템에서 다른 시스템으로 테이블 이전:

이 예시에서는 샘플 데이터셋의 테이블 1개를 사용합니다. 데이터베이스는 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 시스템에서

  • 대상 DB를 생성합니다: 
    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까지(양 끝 포함) 인덱스가 증가하는 세그먼트 주소를 생성합니다. 예를 들어 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 설정으로 제한됩니다.
마지막 수정일 2026년 6월 10일