Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

命名集合

View as MarkdownEdit this pageReport an issueSet up docs MCP

命名集合提供了一种存储键值对集合的方式， 可用于配置与外部源的集成。您可以将命名集合用于 字典、表、表函数和对象存储。

命名集合可以通过 DDL 或在配置文件中进行配置，并在 ClickHouse 启动时生效。它们可以简化对象的创建，并向 没有管理权限的用户隐藏凭据。

命名集合中的键必须与相应 函数、表引擎、数据库等的参数名称匹配。下面的示例中， 每种类型都链接到了对应的参数列表。

在命名集合中设置的参数可以在 SQL 中被覆盖，下面的示例 展示了这一点。可以使用 [NOT] OVERRIDABLE 关键字、XML 属性 和/或配置选项 allow_named_collection_override_by_default 来限制这种能力。

将命名集合存储在 system 数据库中

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>

命名集合的存储

命名集合既可以存储在本地 disk 上，也可以存储在 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。

在配置文件中存储命名集合

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 命名集合

修改或添加集合 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;

删除名为 collection2 的 DDL 命名集合：

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 表的命名集合示例

以下两个示例都使用相同的命名集合 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 数据库和字典的命名集合示例

以下四个示例使用的是同一个命名集合 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 字典

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。此外，还有以下别名：

  • username 是 user 的别名
  • db 是 database 的别名。

PostgreSQL table engine 的连接池设置 (postgresql_connection_pool_size 以及其他 postgresql_* 设置) 也可以存储在集合中，或以 key = value overrides 的形式传递。它们适用于 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 函数示例

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 的字典中使用命名集合的示例

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>

由于使用的是 remoteSecure，因此连接无需 secure，但它可用于字典。

结合命名集合使用 remote/remoteSecure 函数的示例

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

使用源为 ClickHouse 的字典和命名集合的示例

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 表示例

以下两个示例都使用同一个命名集合 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 表和字典的命名集合

有关参数的说明，请参阅 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 字典

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);

┌
Navigation