> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-postgresql-tls-support.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentation sur les collections nommées

# Collections nommées

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Non pris en charge par ClickHouse Cloud
        </div>;
};

Les collections nommées permettent de stocker des ensembles de paires clé-valeur
utilisés pour configurer des intégrations avec des sources externes. Vous pouvez utiliser des collections nommées avec
des dictionnaires, des tables, des fonctions de table et le stockage d’objets.

Les collections nommées peuvent être configurées via du DDL ou dans des fichiers de configuration, et sont prises en compte
au démarrage de ClickHouse. Elles simplifient la création d’objets et permettent de masquer les informations d’authentification
aux utilisateurs sans accès administratif.

Les clés d’une collection nommée doivent correspondre aux noms des paramètres de la
fonction, du moteur de table, de la base de données, etc. correspondants. Dans les exemples ci-dessous, un lien vers la liste des paramètres
est fourni pour chaque type.

Les paramètres définis dans une collection nommée peuvent être remplacés en SQL, comme le montrent les exemples
ci-dessous. Cette possibilité peut être limitée à l’aide des mots-clés `[NOT] OVERRIDABLE` et des attributs XML,
et/ou de l’option de configuration `allow_named_collection_override_by_default`.

<Warning>
  Si le remplacement est autorisé, des utilisateurs sans accès administratif peuvent
  être en mesure de découvrir les informations d’authentification que vous essayez de masquer.
  Si vous utilisez des collections nommées à cette fin, vous devez désactiver
  `allow_named_collection_override_by_default` (qui est activé par défaut).
</Warning>

<div id="storing-named-collections-in-the-system-database">
  ## Stocker des collections nommées dans la base de données système
</div>

<div id="ddl-example">
  ### Exemple de DDL
</div>

```sql theme={null}
CREATE NAMED COLLECTION name AS
key_1 = 'value' OVERRIDABLE,
key_2 = 'value2' NOT OVERRIDABLE,
url = 'https://connection.url/'
```

Dans l’exemple ci-dessus :

* `key_1` peut toujours être surchargée.
* `key_2` ne peut jamais être surchargée.
* `url` peut être surchargée ou non selon la valeur de `allow_named_collection_override_by_default`.

<div id="permissions-to-create-named-collections-with-ddl">
  ### Permissions pour créer des collections nommées avec DDL
</div>

Pour gérer des collections nommées avec DDL, un utilisateur doit disposer du privilège `named_collection_control`.  Ce privilège peut être attribué en ajoutant un fichier à `/etc/clickhouse-server/users.d/`.  Cet exemple accorde à l’utilisateur `default` les privilèges `access_management` et `named_collection_control` :

```xml title='/etc/clickhouse-server/users.d/user_default.xml' highlight={6} theme={null}
<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>
```

<Tip>
  Dans l’exemple ci-dessus, la valeur `password_sha256_hex` est la représentation hexadécimale du hachage SHA256 du mot de passe. Cette configuration pour l’utilisateur `default` comporte l’attribut `replace=true`, car la configuration par défaut définit un `password` en clair, et il n’est pas possible de définir à la fois un mot de passe en clair et un mot de passe SHA256 hexadécimal pour un même utilisateur.
</Tip>

<div id="storage-for-named-collections">
  ### Stockage des collections nommées
</div>

Les collections nommées peuvent être stockées soit sur un disk local, soit dans ZooKeeper/Keeper. Par défaut, le stockage local est utilisé.
Elles peuvent également être stockées de manière chiffrée, avec les mêmes algorithmes que ceux utilisés pour le [chiffrement du disque](/fr/concepts/features/configuration/server-config/storing-data#encrypted-virtual-file-system),
`aes_128_ctr` étant utilisé par défaut.

Pour configurer le stockage des collections nommées, vous devez spécifier un `type`. Il peut s'agir de `local` ou de `keeper`/`zookeeper`. Pour le stockage chiffré,
vous pouvez utiliser `local_encrypted` ou `keeper_encrypted`/`zookeeper_encrypted`.

Pour utiliser ZooKeeper/Keeper, vous devez également définir un `path` (chemin dans ZooKeeper/Keeper où les collections nommées seront stockées) dans la
section `named_collections_storage` du fichier de configuration. L'exemple suivant utilise le chiffrement et ZooKeeper/Keeper :

```xml theme={null}
<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>
```

Le paramètre de configuration facultatif `update_timeout_ms` vaut `5000` par défaut.

<div id="storing-named-collections-in-configuration-files">
  ## Stockage des collections nommées dans des fichiers de configuration
</div>

<div id="xml-example">
  ### Exemple XML
</div>

```xml title='/etc/clickhouse-server/config.d/named_collections.xml' theme={null}
<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>
```

Dans l’exemple ci-dessus :

* `key_1` peut toujours être surchargée.
* `key_2` ne peut jamais être surchargée.
* `url` peut être surchargée ou non selon la valeur de `allow_named_collection_override_by_default`.

<div id="modifying-named-collections">
  ## Modification des collections nommées
</div>

Les collections nommées créées à l’aide de requêtes DDL peuvent être modifiées ou supprimées via des instructions DDL. Les collections nommées créées à partir de fichiers XML peuvent être gérées en modifiant ou en supprimant le fichier XML correspondant.

<div id="alter-a-ddl-named-collection">
  ### Modifier une collection nommée DDL
</div>

Modifiez ou ajoutez les clés `key1` et `key3` de la collection `collection2`
(cela ne modifiera pas la valeur de la propriété `overridable` pour ces clés) :

```sql theme={null}
ALTER NAMED COLLECTION collection2 SET key1=4, key3='value3'
```

Modifiez ou ajoutez la clé `key1` et autorisez sa redéfinition systématique :

```sql theme={null}
ALTER NAMED COLLECTION collection2 SET key1=4 OVERRIDABLE
```

Supprimez la clé `key2` de `collection2` :

```sql theme={null}
ALTER NAMED COLLECTION collection2 DELETE key2
```

Modifiez ou ajoutez la clé `key1` et supprimez la clé `key3` dans la collection `collection2` :

```sql theme={null}
ALTER NAMED COLLECTION collection2 SET key1=4, DELETE key3
```

Pour forcer une clé à utiliser les paramètres par défaut de l’indicateur `overridable`, vous devez
la supprimer, puis l’ajouter à nouveau.

```sql theme={null}
ALTER NAMED COLLECTION collection2 DELETE key1;
ALTER NAMED COLLECTION collection2 SET key1=4;
```

<div id="drop-the-ddl-named-collection-collection2">
  ### Supprimez la collection nommée DDL `collection2` :
</div>

```sql theme={null}
DROP NAMED COLLECTION collection2
```

<div id="named-collections-for-accessing-s3">
  ## Collections nommées pour accéder à S3
</div>

Pour une description des paramètres, voir [fonction de table S3](/fr/reference/functions/table-functions/s3).

<div id="ddl-example">
  ### Exemple de DDL
</div>

```sql theme={null}
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/'
```

<div id="xml-example">
  ### Exemple XML
</div>

```xml theme={null}
<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>
```

<div id="s3-function-and-s3-table-named-collection-examples">
  ### fonction s3() et exemples de collection nommée pour la table S3
</div>

Les deux exemples suivants utilisent la même collection nommée `s3_mydata` :

<div id="s3-function">
  #### Fonction s3()
</div>

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

<Tip>
  Le premier argument de la fonction `s3()` ci-dessus est le nom de la collection, `s3_mydata`. Sans collections nommées, l'identifiant de clé d'accès, le secret, le format et l'URL devraient être fournis à chaque appel de la fonction `s3()`.
</Tip>

<div id="s3-table">
  #### Table S3
</div>

```sql theme={null}
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 │
└────────┘
```

<div id="named-collections-for-accessing-mysql-database">
  ## Collection nommée pour accéder à une base de données MySQL
</div>

Pour une description des paramètres, voir [mysql](/fr/reference/functions/table-functions/mysql).

<div id="ddl-example">
  ### Exemple de DDL
</div>

```sql theme={null}
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
```

<div id="xml-example">
  ### Exemple XML
</div>

```xml theme={null}
<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>
```

<div id="mysql-function-mysql-table-mysql-database-and-dictionary-named-collection-examples">
  ### Exemples de collection nommée pour la fonction `mysql()`, une table MySQL, une base de données MySQL et un dictionnaire
</div>

Les quatre exemples suivants utilisent la même collection nommée `mymysql` :

<div id="mysql-function">
  #### fonction mysql()
</div>

```sql theme={null}
SELECT count() FROM mysql(mymysql, table = 'test');

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

<Note>
  La collection nommée ne spécifie pas le paramètre `table` ; il est donc indiqué dans l'appel de fonction sous la forme `table = 'test'`.
</Note>

<div id="mysql-table">
  #### Table MySQL
</div>

```sql theme={null}
CREATE TABLE mytable(A Int64) ENGINE = MySQL(mymysql, table = 'test', connection_pool_size=3, replace_query=0);
SELECT count() FROM mytable;

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

<Note>
  Le DDL remplace le paramètre connection\_pool\_size de la collection nommée.
</Note>

<div id="mysql-database">
  #### Base de données MySQL
</div>

```sql theme={null}
CREATE DATABASE mydatabase ENGINE = MySQL(mymysql);

SHOW TABLES FROM mydatabase;

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

<div id="mysql-dictionary">
  #### Dictionnaire MySQL
</div>

```sql theme={null}
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                     │
└─────────────────────────┘
```

<div id="named-collections-for-accessing-postgresql-database">
  ## Collections nommées pour accéder à une base de données PostgreSQL
</div>

Pour la description des paramètres, voir [postgresql](/fr/reference/functions/table-functions/postgresql). Il existe également les alias suivants :

* `username` pour `user`
* `db` pour `database`.

Le paramètre `addresses_expr` est utilisé dans une collection à la place de `host:port`. Ce paramètre est facultatif, car d'autres le sont également : `host`, `hostname`, `port`. Le pseudo-code ci-dessous explique l'ordre de priorité :

```sql theme={null}
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
```

Exemple de création :

```sql theme={null}
CREATE NAMED COLLECTION mypg AS
user = 'pguser',
password = 'jw8s0F4',
host = '127.0.0.1',
port = 5432,
database = 'test',
schema = 'test_schema'
```

Exemple de configuration :

```xml theme={null}
<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>
```

<div id="example-of-using-named-collections-with-the-postgresql-function">
  ### Exemple d’utilisation de collections nommées avec la fonction postgresql
</div>

```sql theme={null}
SELECT * FROM postgresql(mypg, table = 'test');

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

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

<div id="example-of-using-named-collections-with-database-with-engine-postgresql">
  ### Exemple d’utilisation de collections nommées avec une base de données avec moteur PostgreSQL
</div>

```sql theme={null}
CREATE TABLE mypgtable (a Int64) ENGINE = PostgreSQL(mypg, table = 'test', schema = 'public');

SELECT * FROM mypgtable;

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

<Note>
  PostgreSQL copie les données de la collection nommée au moment de la création de la table. Toute modification de la collection n'affecte pas les tables existantes.
</Note>

<div id="example-of-using-named-collections-with-database-with-engine-postgresql-1">
  ### Exemple d’utilisation des collections nommées avec une base de données utilisant le moteur PostgreSQL
</div>

```sql theme={null}
CREATE DATABASE mydatabase ENGINE = PostgreSQL(mypg);

SHOW TABLES FROM mydatabase

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

<div id="example-of-using-named-collections-with-a-dictionary-with-source-postgresql">
  ### Exemple d’utilisation de collections nommées avec un dictionnaire dont la source est POSTGRESQL
</div>

```sql theme={null}
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                     │
└─────────────────────────┘
```

<div id="named-collections-for-accessing-a-remote-clickhouse-database">
  ## Collections nommées pour accéder à une base de données ClickHouse distante
</div>

Pour la description des paramètres, consultez [remote](/fr/reference/functions/table-functions/remote#parameters).

Exemple de configuration :

```sql theme={null}
CREATE NAMED COLLECTION remote1 AS
host = 'remote_host',
port = 9000,
database = 'system',
user = 'foo',
password = 'secret',
secure = 1
```

```xml theme={null}
<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` n'est pas nécessaire pour la connexion grâce à `remoteSecure`, mais peut être utilisé pour les dictionnaires.

<div id="example-of-using-named-collections-with-the-remoteremotesecure-functions">
  ### Exemple d’utilisation des collections nommées avec les fonctions `remote`/`remoteSecure`
</div>

```sql theme={null}
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 │
└───┴───┘
```

<div id="example-of-using-named-collections-with-a-dictionary-with-source-clickhouse">
  ### Exemple d’utilisation de collections nommées avec un dictionnaire dont la source est ClickHouse
</div>

```sql theme={null}
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                       │
└─────────────────────────┘
```

<div id="named-collections-for-accessing-kafka">
  ## Collections nommées pour accéder à Kafka
</div>

Pour une description des paramètres, voir [Kafka](/fr/reference/engines/table-engines/integrations/kafka).

<div id="ddl-example">
  ### Exemple de DDL
</div>

```sql theme={null}
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';

```

<div id="xml-example">
  ### Exemple XML
</div>

```xml theme={null}
<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>
```

<div id="example-of-using-named-collections-with-a-kafka-table">
  ### Exemple d’utilisation des collections nommées avec une table Kafka
</div>

Les deux exemples suivants utilisent la même collection nommée `my_kafka_cluster` :

```sql theme={null}
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;
```

<div id="named-collections-for-backups">
  ## Collections nommées pour les sauvegardes
</div>

Pour une description des paramètres, voir [Sauvegarde et restauration](/fr/concepts/features/backup-restore/overview).

<div id="ddl-example">
  ### Exemple de DDL
</div>

```sql theme={null}
BACKUP TABLE default.test to S3(named_collection_s3_backups, 'directory')
```

<div id="xml-example">
  ### Exemple XML
</div>

```xml theme={null}
<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>
```

<div id="named-collections-for-accessing-mongodb-table-and-dictionary">
  ## Collections nommées pour accéder aux tables et dictionnaires MongoDB
</div>

Pour la description des paramètres, voir [mongodb](/fr/reference/functions/table-functions/mongodb).

<div id="ddl-example">
  ### Exemple de DDL
</div>

```sql theme={null}
CREATE NAMED COLLECTION mymongo AS
user = '',
password = '',
host = '127.0.0.1',
port = 27017,
database = 'test',
collection = 'my_collection',
options = 'connectTimeoutMS=10000'
```

<div id="xml-example">
  ### Exemple XML
</div>

```xml theme={null}
<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>
```

<div id="mongodb-table">
  #### Table MongoDB
</div>

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

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

<Note>
  Le DDL surcharge le paramètre d’options de la collection nommée.
</Note>

<div id="mongodb-dictionary">
  #### Dictionnaire MongoDB
</div>

```sql theme={null}
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                     │
└─────────────────────────┘
```

<Note>
  La collection nommée indique `my_collection` comme nom de la collection. Dans l’appel de fonction, ce nom est remplacé par `collection = 'my_dict'` pour sélectionner une autre collection.
</Note>