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

> Документация по именованным коллекциям

# Именованные коллекции

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>
            Не поддерживается в ClickHouse Cloud
        </div>;
};

Именованные коллекции позволяют хранить наборы пар ключ-значение для
настройки интеграций с внешними источниками. Именованные коллекции можно использовать со
словарями, таблицами, табличными функциями и Объектным хранилищем.

Именованные коллекции можно настраивать с помощью DDL или в файлах конфигурации; они применяются
при запуске ClickHouse. Они упрощают создание объектов и позволяют скрывать учетные данные
от пользователей без административного доступа.

Ключи в именованной коллекции должны совпадать с именами параметров соответствующей
функции, движка таблицы, базы данных и т. д. В примерах ниже для каждого типа
приведена ссылка на список параметров.

Параметры, заданные в именованной коллекции, можно переопределять в SQL; это показано в примерах
ниже. Эту возможность можно ограничить с помощью ключевых слов `[NOT] OVERRIDABLE`, XML-атрибутов
и/или параметра конфигурации `allow_named_collection_override_by_default`.

<Warning>
  Если переопределение разрешено, пользователи без административного доступа
  могут получить возможность узнать учетные данные, которые вы пытаетесь скрыть.
  Если вы используете именованные коллекции для этой цели, следует отключить
  `allow_named_collection_override_by_default` (по умолчанию этот параметр включен).
</Warning>

<div id="storing-named-collections-in-the-system-database">
  ## Хранение именованных коллекций в системной базе данных
</div>

<div id="ddl-example">
  ### Пример DDL
</div>

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

<div id="permissions-to-create-named-collections-with-ddl">
  ### Разрешения на создание именованных коллекций с помощью DDL
</div>

Чтобы управлять именованными коллекциями с помощью DDL, пользователь должен иметь привилегию `named_collection_control`. Ее можно назначить, добавив файл в `/etc/clickhouse-server/users.d/`. В этом примере пользователю `default` назначаются привилегии `access_management` и `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>
  В приведённом выше примере значение `password_sha256_hex` — это шестнадцатеричное представление SHA256-хеша пароля. В этой конфигурации для пользователя `default` задан атрибут `replace=true`, поскольку в конфигурации по умолчанию установлен `password` в открытом виде, а для одного пользователя нельзя одновременно задать пароль в открытом виде и пароль в формате SHA256 hex.
</Tip>

<div id="storage-for-named-collections">
  ### Хранение именованных коллекций
</div>

Именованные коллекции можно хранить либо на локальном диске, либо в ZooKeeper/Keeper. По умолчанию используется локальное хранилище.
Их также можно хранить в зашифрованном виде, используя те же алгоритмы, что и для [шифрования диска](/ru/concepts/features/configuration/server-config/storing-data#encrypted-virtual-file-system),
при этом по умолчанию используется `aes_128_ctr`.

Чтобы настроить хранилище именованных коллекций, нужно указать `type`. Это может быть `local` или `keeper`/`zookeeper`. Для зашифрованного хранилища
можно использовать `local_encrypted` или `keeper_encrypted`/`zookeeper_encrypted`.

Чтобы использовать ZooKeeper/Keeper, также нужно указать `path` (путь в ZooKeeper/Keeper, где будут храниться именованные коллекции) в
разделе `named_collections_storage` файла конфигурации. В следующем примере используются шифрование и 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>
```

Необязательный параметр конфигурации `update_timeout_ms` по умолчанию имеет значение `5000`.

<div id="storing-named-collections-in-configuration-files">
  ## Хранение именованных коллекций в конфигурационных файлах
</div>

<div id="xml-example">
  ### Пример 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>
```

В приведённом выше примере:

* `key_1` всегда можно переопределить.
* `key_2` нельзя переопределить никогда.
* `url` можно переопределить или не переопределять — в зависимости от значения `allow_named_collection_override_by_default`.

<div id="modifying-named-collections">
  ## Изменение именованных коллекций
</div>

Именованные коллекции, созданные с помощью DDL-запросов, можно изменять или удалять средствами DDL. Именованными коллекциями, созданными с помощью XML-файлов, можно управлять, редактируя или удаляя соответствующие XML-файлы.

<div id="alter-a-ddl-named-collection">
  ### Изменить именованную DDL-коллекцию
</div>

Измените или добавьте ключи `key1` и `key3` в коллекции `collection2`
(это не изменит значение флага `overridable` для этих ключей):

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

Измените или добавьте ключ `key1` и разрешите всегда его переопределять:

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

Удалите ключ `key2` из коллекции `collection2`:

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

Измените или добавьте ключ `key1`, а также удалите ключ `key3` в коллекции `collection2`:

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

Чтобы принудительно применить к ключу настройки по умолчанию для флага `overridable`, необходимо
удалить ключ и добавить его заново.

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

<div id="drop-the-ddl-named-collection-collection2">
  ### Удалите именованную коллекцию DDL `collection2`:
</div>

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

<div id="named-collections-for-accessing-s3">
  ## Именованные коллекции для доступа к S3
</div>

Описание параметров см. в разделе [табличной функции S3](/ru/reference/functions/table-functions/s3).

<div id="ddl-example">
  ### Пример 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">
  ### Пример 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">
  ### Примеры использования именованной коллекции в функции s3() и таблице S3
</div>

В обоих приведённых ниже примерах используется одна и та же именованная коллекция `s3_mydata`:

<div id="s3-function">
  #### Функция 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>
  Первый аргумент функции `s3()`, показанной выше, — это имя коллекции `s3_mydata`. Без именованных коллекций идентификатор ключа доступа, секретный ключ, формат и URL пришлось бы указывать при каждом вызове функции `s3()`.
</Tip>

<div id="s3-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">
  ## Именованные коллекции для доступа к базе данных MySQL
</div>

Описание параметров см. на странице [mysql](/ru/reference/functions/table-functions/mysql).

<div id="ddl-example">
  ### Пример 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">
  ### Пример 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">
  ### Примеры для функции mysql(), таблицы MySQL, базы данных MySQL и именованной коллекции словарь
</div>

В следующих четырёх примерах используется одна и та же именованная коллекция `mymysql`:

<div id="mysql-function">
  #### Функция mysql()
</div>

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

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

<Note>
  В именованной коллекции параметр `table` не указан, поэтому он задаётся при вызове функции как `table = 'test'`.
</Note>

<div id="mysql-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>
  DDL переопределяет параметр connection\_pool\_size в именованной коллекции.
</Note>

<div id="mysql-database">
  #### База данных MySQL
</div>

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

SHOW TABLES FROM mydatabase;

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

<div id="mysql-dictionary">
  #### Словарь 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">
  ## Именованные коллекции для доступа к базе данных PostgreSQL
</div>

Описание параметров см. в [postgresql](/ru/reference/functions/table-functions/postgresql). Также доступны следующие псевдонимы:

* `username` для `user`
* `db` для `database`.

Параметр `addresses_expr` используется в коллекции вместо `host:port`. Этот параметр необязателен, поскольку есть и другие необязательные параметры: `host`, `hostname`, `port`. Приоритет показан в следующем псевдокоде:

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

Пример создания:

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

Пример конфигурации:

```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">
  ### Пример использования именованных коллекций с функцией 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">
  ### Пример использования именованных коллекций с базой данных на движке 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 копирует данные из именованной коллекции при создании таблицы. Изменения в коллекции не влияют на уже существующие таблицы.
</Note>

<div id="example-of-using-named-collections-with-database-with-engine-postgresql">
  ### Пример использования именованных коллекций с базой данных на движке 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">
  ### Пример использования именованных коллекций со словарём на основе источника 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">
  ## Именованные коллекции для доступа к удалённой базе данных ClickHouse
</div>

Описание параметров приведено в [remote](/ru/reference/functions/table-functions/remote#parameters).

Пример конфигурации:

```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` не нужен для подключения, так как используется `remoteSecure`, но его можно использовать для словарей.

<div id="example-of-using-named-collections-with-the-remoteremotesecure-functions">
  ### Пример использования именованных коллекций в функциях `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">
  ### Пример использования именованных коллекций со словарём на основе 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">
  ## Именованные коллекции для доступа к Kafka
</div>

Описание параметров приведено в разделе [Kafka](/ru/reference/engines/table-engines/integrations/kafka).

<div id="ddl-example">
  ### Пример 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">
  ### Пример 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">
  ### Пример использования именованных коллекций с таблицей Kafka
</div>

В обоих приведённых ниже примерах используется одна и та же именованная коллекция `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">
  ## Именованные коллекции для резервных копий
</div>

Описание параметров см. в разделе [Резервное копирование и восстановление](/ru/concepts/features/backup-restore/overview).

<div id="ddl-example">
  ### Пример DDL
</div>

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

<div id="xml-example">
  ### Пример 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">
  ## Именованные коллекции для доступа к таблице и словарю MongoDB
</div>

См. описание параметров в [mongodb](/ru/reference/functions/table-functions/mongodb).

<div id="ddl-example">
  ### Пример 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">
  ### Пример 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">
  #### Таблица 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>
  DDL переопределяет настройку options в named collection.
</Note>

<div id="mongodb-dictionary">
  #### Словарь 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>
  Именованная коллекция указывает `my_collection` в качестве имени коллекции. В вызове функции это значение переопределяется через `collection = 'my_dict'`, чтобы выбрать другую коллекцию.
</Note>