Colecciones con nombre - ClickHouse Documentation

Las colecciones con nombre ofrecen una forma de almacenar colecciones de pares clave-valor para configurar integraciones con fuentes externas. Puede usar colecciones con nombre con diccionarios, tablas, funciones de tabla y almacenamiento de objetos. Las colecciones con nombre pueden configurarse mediante DDL o en archivos de configuración, y se aplican cuando se inicia ClickHouse. Simplifican la creación de objetos y permiten ocultar credenciales a usuarios sin acceso administrativo. Las claves de una colección con nombre deben coincidir con los nombres de los parámetros de la función, el motor de tabla, la base de datos, etc. correspondientes. En los ejemplos de abajo, se enlaza la lista de parámetros para cada tipo. Los parámetros establecidos en una colección con nombre pueden sobrescribirse en SQL, como se muestra en los ejemplos de abajo. Esta capacidad puede limitarse mediante las palabras clave [NOT] OVERRIDABLE, atributos XML y/o la opción de configuración allow_named_collection_override_by_default.

Si se permite la sobrescritura, es posible que los usuarios sin acceso administrativo averigüen las credenciales que intenta ocultar. Si está usando colecciones con nombre con ese fin, debería deshabilitar allow_named_collection_override_by_default (que está habilitado de forma predeterminada).

Almacenar colecciones con nombre en la base de datos del sistema

Ejemplo de DDL

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

En el ejemplo anterior:

key_1 siempre puede sobrescribirse.
key_2 nunca puede sobrescribirse.
url puede sobrescribirse o no, según el valor de allow_named_collection_override_by_default.

Permisos para crear colecciones con nombre con DDL

Para gestionar colecciones con nombre con DDL, un usuario debe tener el privilegio named_collection_control. Esto se puede asignar añadiendo un archivo a /etc/clickhouse-server/users.d/. En el ejemplo, se otorgan al usuario default los privilegios access_management y 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>
    </default>
  </users>
</clickhouse>

En el ejemplo anterior, el valor password_sha256_hex es la representación hexadecimal del hash SHA256 de la contraseña. Esta configuración para el usuario default tiene el atributo replace=true porque, en la configuración predeterminada, se define una password en texto plano, y no es posible tener configuradas a la vez una contraseña en texto plano y una contraseña SHA256 hexadecimal para un usuario.

Almacenamiento de colecciones con nombre

Las colecciones con nombre pueden almacenarse en el disco local o en ZooKeeper/Keeper. De forma predeterminada, se utiliza el almacenamiento local. También pueden almacenarse cifradas con los mismos algoritmos que se usan para el cifrado de disco, donde aes_128_ctr se utiliza de forma predeterminada. Para configurar el almacenamiento de colecciones con nombre, debe especificar un type. Puede ser local o keeper/zookeeper. Para el almacenamiento cifrado, puede usar local_encrypted o keeper_encrypted/zookeeper_encrypted. Para usar ZooKeeper/Keeper, también es necesario configurar un path (la ruta en ZooKeeper/Keeper donde se almacenarán las colecciones con nombre) en la sección named_collections_storage del archivo de configuración. El siguiente ejemplo usa cifrado y 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>

De forma predeterminada, el parámetro de configuración opcional update_timeout_ms es igual a 5000.

Guardar colecciones con nombre en archivos de configuración

Ejemplo en 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>

En el ejemplo anterior:

key_1 siempre puede sobrescribirse.
key_2 nunca puede sobrescribirse.
url puede sobrescribirse o no, según el valor de allow_named_collection_override_by_default.

Modificar colecciones con nombre

Las colecciones con nombre creadas con consultas DDL pueden modificarse o eliminarse mediante DDL. Las colecciones con nombre creadas con archivos XML pueden gestionarse editando o eliminando el archivo XML correspondiente.

Modificar una colección con nombre DDL

Cambie o añada las claves key1 y key3 de la colección collection2 (esto no cambiará el valor de la marca overridable para esas claves):

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

Cambie o añada la clave key1 y permita sobrescribirla siempre:

ALTER NAMED COLLECTION collection2 SET key1=4 OVERRIDABLE

Elimine la clave key2 de la colección collection2:

ALTER NAMED COLLECTION collection2 DELETE key2

Cambie o añada la clave key1 y elimine la clave key3 de la colección collection2:

ALTER NAMED COLLECTION collection2 SET key1=4, DELETE key3

Para forzar que una clave use la configuración predeterminada del indicador overridable, debes eliminar y volver a añadir la clave.

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

Elimine la colección con nombre de DDL `collection2`:

DROP NAMED COLLECTION collection2

Colecciones con nombre para acceder a S3

Consulte la descripción de los parámetros en la función de tabla S3.

Ejemplo de 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/'

Ejemplo en 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>

Ejemplos de colecciones con nombre de la función s3() y la tabla S3

Ambos ejemplos siguientes usan la misma colección con nombre s3_mydata:

Función s3()

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

El primer argumento de la función s3() anterior es el nombre de la colección, s3_mydata. Sin colecciones con nombre, el ID de la clave de acceso, la clave secreta, el formato y la URL tendrían que pasarse en cada llamada a la función s3().

Tabla de 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;
┌─number─┐
│      0 │
│      1 │
│      2 │
└────────┘

Colecciones con nombre para acceder a una base de datos MySQL

Para consultar la descripción de los parámetros, vea mysql.

Ejemplo de 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

Ejemplo de 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>

Ejemplos de colecciones con nombre para la función mysql(), la tabla MySQL, la base de datos MySQL y el Diccionario

Los cuatro ejemplos siguientes usan la misma colección con nombre mymysql:

función mysql()

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

┌─count()─┐
│       3 │
└─────────┘

La colección con nombre no especifica el parámetro table, por lo que este se indica en la llamada a la función como table = 'test'.

Tabla de MySQL

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

┌─count()─┐
│       3 │
└─────────┘

El DDL anula la configuración connection_pool_size de la colección con nombre.

Base de datos MySQL

CREATE DATABASE mydatabase ENGINE = MySQL(mymysql);

SHOW TABLES FROM mydatabase;

┌─name───┐
│ source │
│ test   │
└────────┘

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

┌─dictGet('dict', 'B', 2)─┐
│ two                     │
└─────────────────────────┘

Colecciones con nombre para acceder a la base de datos PostgreSQL

La descripción de los parámetros puede consultarse en postgresql. Además, existen alias:

username para user
db para database.

El parámetro addresses_expr se usa en una colección en lugar de host:port. Este parámetro es opcional, ya que hay otros parámetros opcionales: host, hostname, port. El siguiente pseudocódigo explica la prioridad:

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

Ejemplo de creación:

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

Ejemplo de configuración:

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

Ejemplo de uso de colecciones con nombre con la función postgresql

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

┌─a─┬─b───┐
│ 2 │ two │
│ 1 │ one │
└───┴─────┘
SELECT * FROM postgresql(mypg, table = 'test', schema = 'public');

┌─a─┐
│ 1 │
│ 2 │
│ 3 │
└───┘

Ejemplo de uso de colecciones con nombre en una base de datos con motor PostgreSQL

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

SELECT * FROM mypgtable;

┌─a─┐
│ 1 │
│ 2 │
│ 3 │
└───┘

PostgreSQL copia los datos de la colección con nombre al crear la tabla. Los cambios en la colección no afectan a las tablas existentes.

Ejemplo de uso de colecciones con nombre con una base de datos con motor PostgreSQL

CREATE DATABASE mydatabase ENGINE = PostgreSQL(mypg);

SHOW TABLES FROM mydatabase

┌─name─┐
│ test │
└──────┘

Ejemplo de uso de colecciones con nombre en un diccionario con fuente 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);

┌─dictGet('dict', 'b', 2)─┐
│ two                     │
└─────────────────────────┘

Colecciones con nombre para acceder a una base de datos remota de ClickHouse

Consulte la descripción de los parámetros en remote. Ejemplo de configuración:

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 no es necesario para la conexión con remoteSecure, pero puede usarse para diccionarios.

Ejemplo de uso de colecciones con nombre con las funciones `remote`/`remoteSecure`

SELECT * FROM remote(remote1, table = one);
┌─dummy─┐
│     0 │
└───────┘

SELECT * FROM remote(remote1, database = merge(system, '^one'));
┌─dummy─┐
│     0 │
└───────┘

INSERT INTO FUNCTION remote(remote1, database = default, table = test) VALUES (1,'a');

SELECT * FROM remote(remote1, database = default, table = test);
┌─a─┬─b─┐
│ 1 │ a │
└───┴───┘

Ejemplo de uso de colecciones con nombre en un diccionario con origen en 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);
┌─dictGet('dict', 'b', 1)─┐
│ a                       │
└─────────────────────────┘

Colecciones con nombre para acceder a Kafka

La descripción de los parámetros se encuentra en Kafka.

Ejemplo de 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';

Ejemplo de 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>

Ejemplo de uso de colecciones con nombre con una tabla de Kafka

Los dos ejemplos siguientes usan la misma colección con nombre 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;

Colecciones con nombre para copias de seguridad

Para ver la descripción de los parámetros, consulte Copias de seguridad y restauración.

Ejemplo de DDL

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

Ejemplo en 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>

Colecciones con nombre para acceder a la tabla y al diccionario de MongoDB

Para obtener la descripción de los parámetros, consulte mongodb.

Ejemplo de DDL

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

Ejemplo de 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>

Tabla de MongoDB

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

┌─count()─┐
│       2 │
└─────────┘

El DDL anula la configuración de opciones de la colección con nombre.

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

┌─dictGet('dict', 'b', 2)─┐
│ two                     │
└─────────────────────────┘

La colección con nombre especifica my_collection como nombre de la colección. En la llamada a la función, este valor se sustituye por collection = 'my_dict' para seleccionar otra colección.

Última modificación el 25 de junio de 2026

Planificación de cargas de trabajoDocumentación sobre la planificación de cargas de trabajo

​Almacenar colecciones con nombre en la base de datos del sistema

​Ejemplo de DDL

​Permisos para crear colecciones con nombre con DDL

​Almacenamiento de colecciones con nombre

​Guardar colecciones con nombre en archivos de configuración

​Ejemplo en XML

​Modificar colecciones con nombre

​Modificar una colección con nombre DDL

​Elimine la colección con nombre de DDL collection2:

​Colecciones con nombre para acceder a S3

​Ejemplo de DDL

​Ejemplo en XML

​Ejemplos de colecciones con nombre de la función s3() y la tabla S3

​Función s3()

​Tabla de S3

​Colecciones con nombre para acceder a una base de datos MySQL

​Ejemplo de DDL

​Ejemplo de XML

​Ejemplos de colecciones con nombre para la función mysql(), la tabla MySQL, la base de datos MySQL y el Diccionario

​función mysql()

​Tabla de MySQL

​Base de datos MySQL

​Diccionario de MySQL

​Colecciones con nombre para acceder a la base de datos PostgreSQL

​Ejemplo de uso de colecciones con nombre con la función postgresql

​Ejemplo de uso de colecciones con nombre en una base de datos con motor PostgreSQL

​Ejemplo de uso de colecciones con nombre con una base de datos con motor PostgreSQL

​Ejemplo de uso de colecciones con nombre en un diccionario con fuente POSTGRESQL

​Colecciones con nombre para acceder a una base de datos remota de ClickHouse

​Ejemplo de uso de colecciones con nombre con las funciones remote/remoteSecure

​Ejemplo de uso de colecciones con nombre en un diccionario con origen en ClickHouse

​Colecciones con nombre para acceder a Kafka

​Ejemplo de DDL

​Ejemplo de XML

​Ejemplo de uso de colecciones con nombre con una tabla de Kafka

​Colecciones con nombre para copias de seguridad

​Ejemplo de DDL

​Ejemplo en XML

​Colecciones con nombre para acceder a la tabla y al diccionario de MongoDB

​Ejemplo de DDL

​Ejemplo de XML

​Tabla de MongoDB

​Diccionario de MongoDB

Almacenar colecciones con nombre en la base de datos del sistema

Ejemplo de DDL

Permisos para crear colecciones con nombre con DDL

Almacenamiento de colecciones con nombre

Guardar colecciones con nombre en archivos de configuración

Ejemplo en XML

Modificar colecciones con nombre

Modificar una colección con nombre DDL

Elimine la colección con nombre de DDL `collection2`:

Colecciones con nombre para acceder a S3

Ejemplo de DDL

Ejemplo en XML

Ejemplos de colecciones con nombre de la función s3() y la tabla S3

Función s3()

Tabla de S3

Colecciones con nombre para acceder a una base de datos MySQL

Ejemplo de DDL

Ejemplo de XML

Ejemplos de colecciones con nombre para la función mysql(), la tabla MySQL, la base de datos MySQL y el Diccionario

función mysql()

Tabla de MySQL

Base de datos MySQL

Diccionario de MySQL

Colecciones con nombre para acceder a la base de datos PostgreSQL

Ejemplo de uso de colecciones con nombre con la función postgresql

Ejemplo de uso de colecciones con nombre en una base de datos con motor PostgreSQL

Ejemplo de uso de colecciones con nombre con una base de datos con motor PostgreSQL

Ejemplo de uso de colecciones con nombre en un diccionario con fuente POSTGRESQL

Colecciones con nombre para acceder a una base de datos remota de ClickHouse

Ejemplo de uso de colecciones con nombre con las funciones `remote`/`remoteSecure`

Ejemplo de uso de colecciones con nombre en un diccionario con origen en ClickHouse

Colecciones con nombre para acceder a Kafka

Ejemplo de DDL

Ejemplo de XML

Ejemplo de uso de colecciones con nombre con una tabla de Kafka

Colecciones con nombre para copias de seguridad

Ejemplo de DDL

Ejemplo en XML

Colecciones con nombre para acceder a la tabla y al diccionario de MongoDB

Ejemplo de DDL

Ejemplo de XML

Tabla de MongoDB

Diccionario de MongoDB