DDL で作成された名前付きコレクションは、一部の ClickHouse Cloud サービスで有効にできます。利用可能かどうかはサポートにお問い合わせください。ClickHouse Cloud では、ユーザーがサーバー設定ファイルを変更できないため、設定ファイルで定義した名前付きコレクションは利用できません。
[NOT] OVERRIDABLE キーワード、XML 属性、および/または設定オプション allow_named_collection_override_by_default を使って制限できます。
system database に 名前付きコレクション を格納する
DDLの例
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
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 で確認できます。
SYSTEM RELOAD CONFIG ではアクティブな backend は変更されません。
設定ファイルに named collections を保存する
XMLの例
/etc/clickhouse-server/config.d/named_collections.xml
key_1は常に上書きできます。key_2は上書きできません。urlは、allow_named_collection_override_by_defaultの値に応じて、上書きできる場合とできない場合があります。
名前付きコレクションの変更
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 collections3_mydata を使用します。
s3() 関数
S3 テーブル
MySQL データベースにアクセスするための 名前付きコレクション
パラメータの説明については、mysql を参照してください。DDLの例
XML の例
mysql() 関数、MySQL テーブル、MySQL データベース、および Dictionary の named collection の例
以下の4つの例では、同じ named collectionmymysql を使用します。
mysql() 関数
名前付きコレクション では
table パラメータが指定されていないため、関数呼び出しで table = 'test' を指定します。MySQLテーブル
DDL は、connection_pool_size の 名前付きコレクション の設定を上書きします。
MySQL データベース
MySQL Dictionary
PostgreSQLデータベースにアクセスするための名前付きコレクション
パラメータの説明については、postgresqlを参照してください。さらに、以下の別名があります。userの別名としてusernamedatabaseの別名としてdb
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 での named collections の使用例
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 collectionmy_kafka_cluster を使用します。
バックアップ用の名前付きコレクション
パラメーターの説明は、バックアップと復元を参照してください。DDL の例
XMLの例
MongoDB Table および Dictionary にアクセスするための named collections
パラメータの説明は mongodb を参照してください。DDLの例
XMLの例
MongoDB テーブル
DDL によって、オプションに指定した 名前付きコレクション の設定は上書きされます。
MongoDB Dictionary
名前付きコレクション では、コレクション名に
my_collection を指定しています。関数呼び出しでは、別のコレクションを選択するために collection = 'my_dict' を指定してこれを上書きします。