Skip to main content
名前付きコレクションは、外部ソースとのインテグレーションを設定するためのキー・バリューのペアの集合を保存する仕組みです。名前付きコレクションは、Dictionary、テーブル、テーブル関数、オブジェクトストレージで使用できます。
DDL で作成された名前付きコレクションは、一部の ClickHouse Cloud サービスで有効にできます。利用可能かどうかはサポートにお問い合わせください。ClickHouse Cloud では、ユーザーがサーバー設定ファイルを変更できないため、設定ファイルで定義した名前付きコレクションは利用できません。
名前付きコレクションは DDL または設定ファイルで設定でき、ClickHouse の起動時に適用されます。これにより、オブジェクトの作成が簡単になるほか、管理者アクセス権のないユーザーに認証情報を見せずに済みます。 名前付きコレクション内のキーは、対応する関数、テーブルエンジン、データベースなどのパラメータ名と一致している必要があります。以下の例では、各タイプごとにパラメータ一覧へのリンクを示しています。 名前付きコレクションに保存されたパラメータをオーバーライドするには、そのコレクションに対する SHOW NAMED COLLECTIONS SECRETS 権限が必要です。これはパラメータに OVERRIDABLE が指定されている場合も同様です。SQL で NOT OVERRIDABLE、または XML で overridable="false" が指定されたキーはオーバーライドできません。コレクションに保存されていないパラメータを追加する場合、この追加権限は不要です。host に対する addresses_expr のような別名も、保存されたパラメータのオーバーライドとして扱われます。
このチェックに必要なのは権限のみであり、シークレットの表示を制御する設定には依存しません。allow_named_collection_override_by_default 設定は廃止されており、何の効果もありません。 Dictionary ソースにも同じルールが適用されます。権限は、Dictionary の作成時、アタッチ時、またはリストア時にチェックされます。Dictionary のロード時には、NOT OVERRIDABLE が指定されたキーに対してのみ制限が適用されます。

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

DDLの例

上記の例では:
  • key_1 は、そのコレクションに対して SHOW NAMED COLLECTIONS SECRETS 権限を持つユーザーであればオーバーライドできます。
  • key_2 は一切オーバーライドできません。
  • url は、そのコレクションに対して SHOW NAMED COLLECTIONS SECRETS 権限を持つユーザーであればオーバーライドできます。

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

DDL で 名前付きコレクション を管理するには、ユーザーに named_collection_control 権限が必要です。これは、/etc/clickhouse-server/users.d/ にファイルを追加することで付与できます。以下の例では、ユーザー default に access_management と named_collection_control の両方の権限を付与しています。
/etc/clickhouse-server/users.d/user_default.xml
上記の例では、password_sha256_hex の値は、パスワードの SHA256 ハッシュを16進数で表したものです。ユーザー default のこの設定に replace=true 属性があるのは、デフォルト設定ですでに平文の password が設定されており、1人のユーザーに平文パスワードと sha256 hex パスワードの両方を設定することはできないためです。
named_collection_control は、ユーザーに 名前付きコレクション の作成・変更・削除を許可しますが、そこに保存済みの値を読み出すことは許可しません。それは別の権限である 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 を使用しています。
省略可能な設定パラメータ update_timeout_ms のデフォルト値は 5000 です。 有効なストレージタイプは、system.server_settings および getServerSetting で確認できます。
保存タイプを変更するには server の再起動が必要です。SYSTEM RELOAD CONFIG ではアクティブな backend は変更されません。

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

XMLの例

/etc/clickhouse-server/config.d/named_collections.xml
上記の例では:
  • key_1 は、そのコレクションに対して SHOW NAMED COLLECTIONS SECRETS 権限を持つユーザーがオーバーライドできます。
  • key_2 はオーバーライドできません。
  • url は、そのコレクションに対して SHOW NAMED COLLECTIONS SECRETS 権限を持つユーザーがオーバーライドできます。

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

DDLクエリで作成した名前付きコレクションは、DDLで変更または削除できます。XMLファイルで作成した名前付きコレクションは、対応するXMLを編集または削除して管理できます。

DDL の named collection を変更する

コレクション collection2 の key1 と key3 を変更または追加します (これらのキーの overridable フラグの値は変更されません) :
key1 キーを変更または追加し、常に上書き可能にします:
collection2 から key2 キーを削除します:
collection2 コレクションのキー key1 を変更または追加し、key3 を削除します:
overridable フラグのデフォルト設定をキーに適用するには、 そのキーを削除してから再度追加する必要があります。

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

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

パラメータの説明については、s3テーブル関数を参照してください。

DDLの例

XMLの例

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

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

s3() 関数

上記の s3() 関数の最初の引数は、名前付きコレクション s3_mydata の名前です。名前付きコレクションを使用しない場合は、アクセスキー ID、シークレット、フォーマット、URL を毎回 s3() 関数の呼び出し時に渡す必要があります。

S3 テーブル

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

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

DDLの例

XML の例

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

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

mysql() 関数

名前付きコレクション では table パラメータが指定されていないため、関数呼び出しで table = 'test' を指定します。

MySQLテーブル

DDL は、connection_pool_size の 名前付きコレクション の設定を上書きします。

MySQL データベース

MySQL Dictionary

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 といった他の省略可能なパラメータがあるためです。優先順位は次の疑似コードで説明します。
作成例:
設定例:

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

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

PostgreSQL では、テーブルの作成時に名前付きコレクションからデータがコピーされます。後からコレクションを変更しても、既存のテーブルには反映されません。

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

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

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

パラメータの説明は、remote を参照してください。 設定例:
secure は、接続には remoteSecure があるため必要ありませんが、辞書では使用できます。

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

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

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

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

DDLの例

XMLの例

OAUTHBEARER/OIDC 認証

OAUTHBEARER のオプションは librdkafka の拡張設定であるため、各名前付きコレクション内の <kafka> の下にネストして指定する必要があります。トップレベルの kafka_* キーは、Kafka テーブルエンジンの設定に使用されます。ClickHouse は、ネストされた XML 要素名に含まれるアンダースコアをピリオドに変換したうえで librdkafka に渡します。 次の例では、Azure Event Hubs のネームスペース向けに OAuth クライアント認証情報を設定します。
/etc/clickhouse-server/config.d/named_collections.xml
ENGINE = Kafka(eventhub_one) で名前付きコレクションを使用する場合、ClickHouseはサーバー全体のグローバルな <kafka> 設定をマージしません。broker アドレスまたはOAuthスコープが異なる場合は、Event Hubsのネームスペースごとにコレクションを1つずつ作成し、必要なOIDCプロパティをすべてそのコレクションに含めてください。 この例の from_env 属性は、XMLで定義された名前付きコレクションに適用され、ClickHouseサーバープロセスの環境から値を読み取ります。デプロイ方法やデフォルト値の詳細については 環境変数による置換 を、前処理済みの設定ファイル内のシークレットを保護する方法については 設定の暗号化と秘匿化 を参照してください。

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

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

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

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

DDL の例

XMLの例

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

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

DDLの例

XMLの例

MongoDB テーブル

DDL によって、オプションに指定した 名前付きコレクション の設定は上書きされます。

MongoDB Dictionary

この Dictionary は、名前付きコレクションで指定されている my_collection を使用します。別の MongoDB コレクションを使用するには、そのコレクションを値として指定した名前付きコレクションを別途定義してください。