名前付きコレクション

名前付きコレクションは、外部ソースとのインテグレーションを設定するためのキー・バリューのペアの集合を保存する仕組みです。名前付きコレクションは、辞書、テーブル、テーブル関数、オブジェクトストレージで使用できます。

名前付きコレクションは DDL または設定ファイルで設定でき、ClickHouse の起動時に適用されます。これにより、オブジェクトの作成が簡単になるほか、管理者アクセス権のないユーザーに認証情報を見せずに済みます。

名前付きコレクション内のキーは、対応する関数、テーブルエンジン、データベースなどのパラメータ名と一致している必要があります。以下の例では、各タイプごとにパラメータ一覧へのリンクを示しています。

名前付きコレクションで設定したパラメータは SQL でオーバーライドできます。これについては以下の例で示します。この動作は、[NOT] OVERRIDABLE キーワード、XML 属性、および/または設定オプション allow_named_collection_override_by_default を使って制限できます。

system database に名前付きコレクションを格納する

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.xmlxml

<clickhouse>
  <users>
    <default>
      <password_sha256_hex>65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5</password_sha256_hex replace=true>
      <access_management>1</access_management>
      <named_collection_control>1</named_collection_control>
    </default>
  </users>
</clickhouse>

名前付きコレクションの保存先

名前付きコレクションは、ローカルディスクまたは 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';

保存タイプを変更するには server の再起動が必要です。SYSTEM RELOAD CONFIG ではアクティブな backend は変更されません。

設定ファイルに named collections を保存する

XMLの例

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

<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で変更または削除できます。XMLファイルで作成した名前付きコレクションは、対応するXMLを編集または削除して管理できます。

DDL の named collection を変更する

コレクション 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テーブル関数を参照してください。

DDLの例

CREATE NAMED COLLECTION s3_mydata AS
access_key_id = 'AKIAIOSFODNN7EXAMPLE',
secret_access_key = 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
format = 'CSV',
url = 'https://s3.us-east-1.amazonaws.com/yourbucket/mydata/'

XMLの例

<clickhouse>
    <named_collections>
        <s3_mydata>
            <access_key_id>AKIAIOSFODNN7EXAMPLE</access_key_id>
            <secret_access_key>wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY</secret_access_key>
            <format>CSV</format>
            <url>https://s3.us-east-1.amazonaws.com/yourbucket/mydata/</url>
        </s3_mydata>
    </named_collections>
</clickhouse>

s3() 関数と S3テーブルの named collection の例

以下の 2 つの例では、どちらも同じ named collection s3_mydata を使用します。

s3() 関数

INSERT INTO FUNCTION s3(s3_mydata, filename = 'test_file.tsv.gz',
   format = 'TSV', structure = 'number UInt64', compression_method = 'gzip')
SELECT * FROM numbers(10000);

S3 テーブル

CREATE TABLE s3_engine_table (number Int64)
ENGINE=S3(s3_mydata, url='https://s3.us-east-1.amazonaws.com/yourbucket/mydata/test_file.tsv.gz', format = 'TSV')
SETTINGS input_format_with_names_use_header = 0;

SELECT * FROM s3_engine_table LIMIT 3;
┌

MySQL データベースにアクセスするための名前付きコレクション

パラメータの説明については、mysql を参照してください。

DDLの例

CREATE NAMED COLLECTION mymysql AS
user = 'myuser',
password = 'mypass',
host = '127.0.0.1',
port = 3306,
database = 'test',
connection_pool_size = 8,
replace_query = 1

XML の例

<clickhouse>
    <named_collections>
        <mymysql>
            <user>myuser</user>
            <password>mypass</password>
            <host>127.0.0.1</host>
            <port>3306</port>
            <database>test</database>
            <connection_pool_size>8</connection_pool_size>
            <replace_query>1</replace_query>
        </mymysql>
    </named_collections>
</clickhouse>

mysql() 関数、MySQL テーブル、MySQL データベース、および Dictionary の named collection の例

以下の4つの例では、同じ named collection mymysql を使用します。

mysql() 関数

SELECT count() FROM mysql(mymysql, table = 'test');

┌

MySQLテーブル

CREATE TABLE mytable(A Int64) ENGINE = MySQL(mymysql, table = 'test', connection_pool_size=3, replace_query=0);
SELECT count() FROM mytable;

┌

MySQL データベース

CREATE DATABASE mydatabase ENGINE = MySQL(mymysql);

SHOW TABLES FROM mydatabase;

┌

MySQL Dictionary

CREATE DICTIONARY dict (A Int64, B String)
PRIMARY KEY A
SOURCE(MYSQL(NAME mymysql TABLE 'source'))
LIFETIME(MIN 1 MAX 2)
LAYOUT(HASHED());

SELECT dictGet('dict', 'B', 2);

┌

PostgreSQLデータベースにアクセスするための名前付きコレクション

パラメータの説明については、postgresqlを参照してください。さらに、以下の別名があります。

user の別名として username
database の別名として db

PostgreSQL table engine の接続プール設定 (postgresql_connection_pool_size およびその他の postgresql_* 設定) も、コレクションに保存するか、key = value 形式のオーバーライドとして渡すことができます。これらは PostgreSQL テーブルエンジン、postgresql テーブル関数、および PostgreSQL データベースエンジンに適用されます。テーブルで明示的に指定した SETTINGS clause は、コレクション内の値よりも優先されます。

パラメータ addresses_expr は、コレクション内では host:port の代わりに使用します。このパラメータは省略可能です。これは、host、hostname、port といった他の省略可能なパラメータがあるためです。優先順位は次の疑似コードで説明します。

CASE
    WHEN collection['addresses_expr'] != '' THEN collection['addresses_expr']
    WHEN collection['host'] != ''           THEN collection['host'] || ':' || if(collection['port'] != '', collection['port'], '5432')
    WHEN collection['hostname'] != ''       THEN collection['hostname'] || ':' || if(collection['port'] != '', collection['port'], '5432')
END

作成例:

CREATE NAMED COLLECTION mypg AS
user = 'pguser',
password = 'jw8s0F4',
host = '127.0.0.1',
port = 5432,
database = 'test',
schema = 'test_schema'

設定例:

<clickhouse>
    <named_collections>
        <mypg>
            <user>pguser</user>
            <password>jw8s0F4</password>
            <host>127.0.0.1</host>
            <port>5432</port>
            <database>test</database>
            <schema>test_schema</schema>
        </mypg>
    </named_collections>
</clickhouse>

postgresql 関数で named collections を使用する例

SELECT * FROM postgresql(mypg, table = 'test');

┌

PostgreSQLエンジンのデータベースで名前付きコレクションを使用する例

CREATE TABLE mypgtable (a Int64) ENGINE = PostgreSQL(mypg, table = 'test', schema = 'public');

SELECT * FROM mypgtable;

┌

PostgreSQLエンジンのデータベースで名前付きコレクションを使用する例

CREATE DATABASE mydatabase ENGINE = PostgreSQL(mypg);

SHOW TABLES FROM mydatabase

┌

ソースが POSTGRESQL の Dictionary で名前付きコレクションを使用する例

CREATE DICTIONARY dict (a Int64, b String)
PRIMARY KEY a
SOURCE(POSTGRESQL(NAME mypg TABLE test))
LIFETIME(MIN 1 MAX 2)
LAYOUT(HASHED());

SELECT dictGet('dict', 'b', 2);

┌

リモート ClickHouse データベースにアクセスするための名前付きコレクション

パラメータの説明は、remote を参照してください。

設定例:

CREATE NAMED COLLECTION remote1 AS
host = 'remote_host',
port = 9000,
database = 'system',
user = 'foo',
password = 'secret',
secure = 1

<clickhouse>
    <named_collections>
        <remote1>
            <host>remote_host</host>
            <port>9000</port>
            <database>system</database>
            <user>foo</user>
            <password>secret</password>
            <secure>1</secure>
        </remote1>
    </named_collections>
</clickhouse>

secure は、接続には remoteSecure があるため必要ありませんが、辞書では使用できます。

`remote`/`remoteSecure` 関数で named collections を使う例

SELECT * FROM remote(remote1, table = one);
┌

ソースが ClickHouse の Dictionary での named collections の使用例

CREATE DICTIONARY dict(a Int64, b String)
PRIMARY KEY a
SOURCE(CLICKHOUSE(NAME remote1 TABLE test DB default))
LIFETIME(MIN 1 MAX 2)
LAYOUT(HASHED());

SELECT dictGet('dict', 'b', 1);
┌

Kafka へのアクセス用の名前付きコレクション

パラメータの説明は、Kafka を参照してください。

DDLの例

CREATE NAMED COLLECTION my_kafka_cluster AS
kafka_broker_list = 'localhost:9092',
kafka_topic_list = 'kafka_topic',
kafka_group_name = 'consumer_group',
kafka_format = 'JSONEachRow',
kafka_max_block_size = '1048576';

XMLの例

<clickhouse>
    <named_collections>
        <my_kafka_cluster>
            <kafka_broker_list>localhost:9092</kafka_broker_list>
            <kafka_topic_list>kafka_topic</kafka_topic_list>
            <kafka_group_name>consumer_group</kafka_group_name>
            <kafka_format>JSONEachRow</kafka_format>
            <kafka_max_block_size>1048576</kafka_max_block_size>
        </my_kafka_cluster>
    </named_collections>
</clickhouse>

Kafkaテーブルで named collection を使用する例

以下の2つの例では、どちらも同じ named collection my_kafka_cluster を使用します。

CREATE TABLE queue
(
    timestamp UInt64,
    level String,
    message String
)
ENGINE = Kafka(my_kafka_cluster)

CREATE TABLE queue
(
    timestamp UInt64,
    level String,
    message String
)
ENGINE = Kafka(my_kafka_cluster)
SETTINGS kafka_num_consumers = 4,
         kafka_thread_per_consumer = 1;

バックアップ用の名前付きコレクション

パラメーターの説明は、バックアップと復元を参照してください。

DDL の例

BACKUP TABLE default.test to S3(named_collection_s3_backups, 'directory')

XMLの例

<clickhouse>
    <named_collections>
        <named_collection_s3_backups>
            <url>https://my-s3-bucket.s3.amazonaws.com/backup-S3/</url>
            <access_key_id>ABC123</access_key_id>
            <secret_access_key>Abc+123</secret_access_key>
        </named_collection_s3_backups>
    </named_collections>
</clickhouse>

MongoDB Table および Dictionary にアクセスするための named collections

パラメータの説明は mongodb を参照してください。

DDLの例

CREATE NAMED COLLECTION mymongo AS
user = '',
password = '',
host = '127.0.0.1',
port = 27017,
database = 'test',
collection = 'my_collection',
options = 'connectTimeoutMS=10000'

XMLの例

<clickhouse>
    <named_collections>
        <mymongo>
            <user></user>
            <password></password>
            <host>127.0.0.1</host>
            <port>27017</port>
            <database>test</database>
            <collection>my_collection</collection>
            <options>connectTimeoutMS=10000</options>
        </mymongo>
    </named_collections>
</clickhouse>

MongoDB テーブル

CREATE TABLE mytable(log_type VARCHAR, host VARCHAR, command VARCHAR) ENGINE = MongoDB(mymongo, options='connectTimeoutMS=10000&compressors=zstd')
SELECT count() FROM mytable;

┌

MongoDB Dictionary

CREATE DICTIONARY dict
(
    `a` Int64,
    `b` String
)
PRIMARY KEY a
SOURCE(MONGODB(NAME mymongo COLLECTION my_dict))
LIFETIME(MIN 1 MAX 2)
LAYOUT(HASHED())

SELECT dictGet('dict', 'b', 2);

┌

名前付きコレクション

system database に 名前付きコレクション を格納する

DDLの例

DDL を使用して 名前付きコレクション を作成するための権限

名前付きコレクションの保存先

設定ファイルに named collections を保存する

XMLの例

名前付きコレクションの変更

DDL の named collection を変更する

DDL の名前付きコレクション collection2 を削除します:

S3 にアクセスするための名前付きコレクション

DDLの例

XMLの例

s3() 関数と S3テーブルの named collection の例

s3() 関数

S3 テーブル

MySQL データベースにアクセスするための 名前付きコレクション

DDLの例

XML の例

mysql() 関数、MySQL テーブル、MySQL データベース、および Dictionary の named collection の例

mysql() 関数

MySQLテーブル

MySQL データベース

MySQL Dictionary

PostgreSQLデータベースにアクセスするための名前付きコレクション

postgresql 関数で named collections を使用する例

PostgreSQLエンジンのデータベースで名前付きコレクションを使用する例

PostgreSQLエンジンのデータベースで名前付きコレクションを使用する例

ソースが POSTGRESQL の Dictionary で 名前付きコレクション を使用する例

リモート ClickHouse データベースにアクセスするための名前付きコレクション

remote/remoteSecure 関数で named collections を使う例

ソースが ClickHouse の Dictionary での named collections の使用例

Kafka へのアクセス用の名前付きコレクション

DDLの例

XMLの例

Kafkaテーブルで named collection を使用する例

バックアップ用の名前付きコレクション

DDL の例

XMLの例

MongoDB Table および Dictionary にアクセスするための named collections

DDLの例

XMLの例

MongoDB テーブル

MongoDB Dictionary

system database に名前付きコレクションを格納する

DDL を使用して名前付きコレクションを作成するための権限

DDL の名前付きコレクション `collection2` を削除します:

MySQL データベースにアクセスするための名前付きコレクション

ソースが POSTGRESQL の Dictionary で名前付きコレクションを使用する例

`remote`/`remoteSecure` 関数で named collections を使う例