네임드 컬렉션(Named Collections)

네임드 컬렉션은 외부 소스와의 통합을 구성하는 데 사용되는 키-값 쌍의 컬렉션을 저장하는 방법을 제공합니다. 딕셔너리, 테이블, 테이블 함수, 오브젝트 스토리지와 함께 사용할 수 있습니다. 이 문서에서는 생성 방법과 오버라이드 규칙, 저장 방식, 수정 방법을 설명할게요.

출처: 문서

본문

네임드 컬렉션은 외부 소스와의 통합을 구성하는 데 사용되는 키-값 쌍의 컬렉션을 저장하는 방법을 제공합니다. 네임드 컬렉션을 딕셔너리, 테이블, 테이블 함수, 오브젝트 스토리지와 함께 사용할 수 있습니다.

DDL로 생성된 네임드 컬렉션은 선택된 ClickHouse Cloud 서비스에서 활성화할 수 있습니다. 가용성을 확인하려면 지원팀에 문의하세요. ClickHouse Cloud에서는 사용자가 서버 구성 파일을 수정할 수 없으므로 구성 파일에 정의된 네임드 컬렉션은 사용할 수 없습니다.

네임드 컬렉션은 DDL 또는 구성 파일로 구성할 수 있으며 ClickHouse가 시작될 때 적용됩니다. 이들은 객체 생성을 단순화하고 관리자 접근 권한이 없는 사용자로부터 자격 증명을 숨깁니다. 네임드 컬렉션의 키는 해당 함수, 테이블 엔진, 데이터베이스 등의 매개변수 이름과 일치해야 합니다. 아래 예제들에서 매개변수 목록은 각 유형에 대해 링크되어 있습니다. 네임드 컬렉션에 설정된 매개변수는 SQL에서 재정의할 수 있으며, 이것은 아래 예제들에 나와 있습니다. 이 능력은 [NOT] OVERRIDABLE 키워드와 XML 속성 및/또는 allow_named_collection_override_by_default 구성 옵션을 사용해 제한할 수 있습니다.

오버라이드가 허용되면 관리자 접근 권한이 없는 사용자가 숨기려는 자격 증명을 알아낼 수 있을 수도 있습니다. 그 목적으로 네임드 컬렉션을 사용한다면 allow_named_collection_override_by_default(기본적으로 활성화됨)를 비활성화해야 합니다.

시스템 데이터베이스에 네임드 컬렉션 저장하기

DDL 예제

CREATE NAMED COLLECTION name AS
key_1 = 'value' OVERRIDABLE,
key_2 = 'value2' NOT OVERRIDABLE,
url = 'https://connection.url/'

위 예제에서:

key_1은 항상 오버라이드할 수 있습니다.
key_2는 절대 오버라이드할 수 없습니다.
url은 allow_named_collection_override_by_default의 값에 따라 오버라이드되거나 되지 않습니다.

DDL로 네임드 컬렉션 생성 권한

DDL로 네임드 컬렉션을 관리하려면 사용자가 named_collection_control 권한을 가져야 합니다. 이것은 /etc/clickhouse-server/users.d/에 파일을 추가해 할당할 수 있습니다. 예제는 default 사용자에게 access_management와 named_collection_control 권한을 모두 부여합니다:

/etc/clickhouse-server/users.d/user_default.xml

<clickhouse>
  <users>
    <default>
      <password_sha256_hex>65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5</password_sha256_hex replace=true>
      <access_management>1</access_management>
      <named_collection_control>1</named_collection_control>
      <!-- 주석을 해제하면 이 사용자가 네임드 컬렉션에 저장된 값도 볼 수 있습니다. -->
      <!-- <show_named_collections_secrets>1</show_named_collections_secrets> -->
    </default>
  </users>
</clickhouse>

위 예제에서 password_sha256_hex 값은 비밀번호의 SHA256 해시의 16진수 표현입니다. default 사용자에 대한 이 구성은 replace=true 속성을 가집니다. 기본 구성에서는 일반 텍스트 password가 설정되어 있고, 한 사용자에 일반 텍스트와 sha256 hex 비밀번호를 모두 설정할 수는 없기 때문입니다.

named_collection_control은 사용자가 네임드 컬렉션을 생성, 변경, drop할 수 있게 하지만 이미 저장된 값을 다시 읽지는 못하게 합니다. 그것은 show_named_collections_secrets 설정으로 활성화되는 별도의 권한 SHOW NAMED COLLECTIONS SECRETS입니다. 사용자는 자신이 가진 권한만 부여할 수 있으므로, show_named_collections_secrets가 비활성화된 동안 사용자는 완전한 권한 집합을 갖지 못하며 GRANT ALL ON *.* TO another_user WITH GRANT OPTION이 (Missing permissions: SHOW NAMED COLLECTIONS SECRETS ON *)로 거부됩니다.

네임드 컬렉션 저장소

네임드 컬렉션은 로컬 디스크 또는 ZooKeeper/Keeper에 저장할 수 있습니다. 기본적으로 로컬 저장소가 사용됩니다. 디스크 암호화에 사용되는 것과 같은 알고리즘으로 암호화하여 저장할 수도 있으며, 기본적으로 aes_128_ctr가 사용됩니다. 네임드 컬렉션 저장소를 구성하려면 type을 지정해야 합니다. 이것은 local 또는 keeper/zookeeper일 수 있습니다. 암호화 저장소의 경우 local_encrypted 또는 keeper_encrypted/zookeeper_encrypted를 사용할 수 있습니다. ZooKeeper/Keeper를 사용하려면 구성 파일의 named_collections_storage 섹션에 path(네임드 컬렉션이 저장될 ZooKeeper/Keeper의 경로)도 설정해야 합니다. 다음 예제는 암호화와 ZooKeeper/Keeper를 사용합니다:

<clickhouse>
  <named_collections_storage>
    <type>zookeeper_encrypted</type>
    <key_hex>bebec0cabebec0cabebec0cabebec0ca</key_hex>
    <algorithm>aes_128_ctr</algorithm>
    <path>/named_collections_path/</path>
    <update_timeout_ms>1000</update_timeout_ms>
  </named_collections_storage>
</clickhouse>

선택적 구성 매개변수 update_timeout_ms는 기본값이 5000입니다. 활성 저장소 유형은 system.server_settings와 getServerSetting을 통해 검사할 수 있습니다:

SELECT value, getServerSetting('named_collections_storage_type')
FROM system.server_settings
WHERE name = 'named_collections_storage.type';

저장소 유형을 변경하려면 서버 재시작이 필요합니다. SYSTEM RELOAD CONFIG는 활성 백엔드를 변경하지 않습니다.

구성 파일에 네임드 컬렉션 저장하기

XML 예제

/etc/clickhouse-server/config.d/named_collections.xml

<clickhouse>
     <named_collections>
        <name>
            <key_1 overridable="true">value</key_1>
            <key_2 overridable="false">value_2</key_2>
            <url>https://connection.url/</url>
        </name>
     </named_collections>
</clickhouse>

위 예제에서:

key_1은 항상 오버라이드할 수 있습니다.
key_2는 절대 오버라이드할 수 없습니다.
url은 allow_named_collection_override_by_default의 값에 따라 오버라이드되거나 되지 않습니다.

네임드 컬렉션 수정하기

DDL 쿼리로 생성된 네임드 컬렉션은 DDL로 변경하거나 drop할 수 있습니다. XML 파일로 생성된 네임드 컬렉션은 해당 XML을 편집하거나 삭제하여 관리할 수 있습니다.

DDL 네임드 컬렉션 변경하기

collection2 컬렉션의 키 key1과 key3을 변경하거나 추가합니다(해당 키의 overridable 플래그 값은 변경되지 않습니다):

ALTER NAMED COLLECTION collection2 SET key1=4, key3='value3'

키 key1을 변경하거나 추가하고 항상 오버라이드 가능하게 허용합니다:

ALTER NAMED COLLECTION collection2 SET key1=4 OVERRIDABLE

collection2에서 키 key2를 제거합니다:

ALTER NAMED COLLECTION collection2 DELETE key2

collection2 컬렉션의 키 key1을 변경하거나 추가하고 키 key3을 삭제합니다:

ALTER NAMED COLLECTION collection2 SET key1=4, DELETE key3

키가 overridable 플래그의 기본 설정을 사용하도록 강제하려면 키를 제거한 다음 다시 추가해야 합니다:

ALTER NAMED COLLECTION collection2 DELETE key1;
ALTER NAMED COLLECTION collection2 SET key1=4;

DDL 네임드 컬렉션 collection2 제거하기:

DROP NAMED COLLECTION collection2

S3 접근용 네임드 컬렉션

매개변수 설명은 s3 테이블 함수를 참고하세요.

CREATE NAMED COLLECTION s3_mydata AS
access_key_id = 'AWS_ACCESS_KEY_ID' OVERRIDABLE,
secret_access_key = 'AWS_SECRET_ACCESS_KEY' OVERRIDABLE,
format = 'CSV',
url = 'https://my-bucket.s3.amazonaws.com/my-file.csv'

다음의 s3() 함수와 S3 테이블 예제는 같은 네임드 컬렉션 s3_mydata를 사용합니다:

s3() 함수

SELECT * FROM s3(s3_mydata)

위 s3() 함수의 첫 번째 인자는 컬렉션 이름 s3_mydata입니다. 네임드 컬렉션이 없으면 access key ID, 시크릿, 형식, URL이 모두 s3() 함수를 호출할 때마다 전달되어야 합니다.

S3 테이블

CREATE TABLE my_table
ENGINE = S3(s3_mydata)

MySQL 데이터베이스 접근용 네임드 컬렉션

매개변수 설명은 mysql을 참고하세요.

CREATE NAMED COLLECTION mymysql AS
host = '127.0.0.1',
port = 3306,
user = 'clickhouse',
password = 'clickhouse',
database = 'test'

다음 네 가지 예제(mysql() 함수, MySQL 테이블, MySQL 데이터베이스, 딕셔너리)는 같은 네임드 컬렉션 mymysql을 사용합니다:

mysql() 함수

네임드 컬렉션은 table 매개변수를 지정하지 않으므로 함수 호출에서 table = 'test'로 지정됩니다.

MySQL 테이블

CREATE TABLE my_mysql_table
ENGINE = MySQL(mymysql, table = 'test')
SETTINGS connection_pool_size = 6

DDL은 connection_pool_size의 네임드 컬렉션 설정을 오버라이드합니다.

MySQL 데이터베이스

CREATE DATABASE my_mysql_db
ENGINE = MySQL(mymysql, table_overrides = [...])

MySQL 딕셔너리

CREATE DICTIONARY my_mysql_dict
(...)
SOURCE(MYSQL(NAME mymysql))

PostgreSQL 데이터베이스 접근용 네임드 컬렉션

매개변수 설명은 postgresql을 참고하세요. 추가로 별칭이 있습니다:

user에 대한 username
database에 대한 db

PostgreSQL 테이블 엔진의 연결 풀 설정(postgresql_connection_pool_size 및 기타 postgresql_* 설정)도 컬렉션에 저장하거나 key = value 오버라이드로 전달할 수 있습니다. 이것들은 PostgreSQL 테이블 엔진, postgresql 테이블 함수, PostgreSQL 데이터베이스 엔진에 적용됩니다. 테이블의 명시적 SETTINGS 절은 컬렉션의 값보다 우선합니다. 컬렉션에서는 매개변수 addresses_expr가 host:port 대신 사용됩니다. 이 매개변수는 선택 사항인데, 다른 선택적 매개변수들(host, hostname, port)이 있기 때문입니다.

생성 예제:

CREATE NAMED COLLECTION mypg AS
addresses_expr = '127.0.0.1:5432',
user = 'clickhouse',
password = 'clickhouse',
db = 'mydb'

postgresql 함수와 함께 사용 예제:

SELECT * FROM postgresql(mypg, table = 'mytable')

PostgreSQL 엔진 데이터베이스와 함께 사용 예제:

CREATE DATABASE my_pg_db
ENGINE = PostgreSQL(mypg, schema = 'myschema')

PostgreSQL은 테이블이 생성될 때 네임드 컬렉션에서 데이터를 복사합니다. 컬렉션의 변경은 기존 테이블에 영향을 주지 않습니다.

소스가 POSTGRESQL인 딕셔너리와 함께 사용 예제:

CREATE DICTIONARY my_pg_dict
(...)
SOURCE(POSTGRESQL(NAME mypg))

원격 ClickHouse 데이터베이스 접근용 네임드 컬렉션

매개변수 설명은 remote를 참고하세요.

CREATE NAMED COLLECTION mych AS
host = '127.0.0.1',
port = 9000,
user = 'clickhouse',
password = 'clickhouse',
secure = 1,
db = 'mydb'

remoteSecure 때문에 secure는 연결에 필요하지 않지만 딕셔너리에는 사용할 수 있습니다.

remote / remoteSecure 함수와 함께 사용 예제:

SELECT * FROM remote(mych, table = 'mytable')

소스가 ClickHouse인 딕셔너리와 함께 사용 예제:

CREATE DICTIONARY my_ch_dict
(...)
SOURCE(CLICKHOUSE(NAME mych, table = 'mytable'))

Kafka 접근용 네임드 컬렉션

매개변수 설명은 Kafka를 참고하세요.

CREATE NAMED COLLECTION my_kafka_cluster AS
kafka_broker_list = 'host:port',
kafka_security_protocol = 'SSL',
kafka_sasl_mechanisms = 'PLAIN',
kafka_sasl_username = 'clickhouse',
kafka_sasl_password = 'clickhouse'

다음 두 예제는 같은 네임드 컬렉션 my_kafka_cluster를 사용합니다:

Kafka 테이블과 함께 사용 예제:

CREATE TABLE kafka_table
ENGINE = Kafka(my_kafka_cluster)
SETTINGS kafka_format = 'JSONEachRow'

백업용 네임드 컬렉션

매개변수 설명은 Backup and Restore를 참고하세요.

CREATE NAMED COLLECTION my_backup AS
type = 's3',
url = 'https://my-bucket.s3.amazonaws.com/backups/',
access_key_id = 'AWS_ACCESS_KEY_ID',
secret_access_key = 'AWS_SECRET_ACCESS_KEY'

BACKUP TABLE my_table TO my_backup

MongoDB 테이블 및 딕셔너리 접근용 네임드 컬렉션

매개변수 설명은 mongodb를 참고하세요.

CREATE NAMED COLLECTION my_mongo AS
host = '127.0.0.1',
port = 27017,
user = 'clickhouse',
password = 'clickhouse',
database = 'mydb'

MongoDB 테이블:

CREATE TABLE mongo_table
ENGINE = MongoDB(my_mongo)
SETTINGS options = ['connectTimeoutMS=100000'] -- DDL이 options의 네임드 컬렉션 설정을 오버라이드

MongoDB 딕셔너리:

CREATE DICTIONARY mongo_dict
(...)
SOURCE(MONGODB(NAME my_mongo, collection = 'my_dict'))

네임드 컬렉션은 컬렉션 이름으로 my_collection을 지정하지 않습니다. 함수 호출에서 collection = 'my_dict'로 덮어써 다른 컬렉션을 선택합니다.

네임드 컬렉션(Named Collections)