Перейти к основному содержанию
Именованные коллекции позволяют хранить наборы пар ключ-значение для настройки интеграций с внешними источниками. Именованные коллекции можно использовать со словарями, таблицами, табличными функциями и Объектным хранилищем.
Именованные коллекции, созданные с помощью DDL, можно включить в некоторых сервисах ClickHouse Cloud. Чтобы подтвердить доступность, обратитесь в службу поддержки. Именованные коллекции, определенные в файлах конфигурации, недоступны, поскольку пользователи не могут изменять файлы конфигурации сервера в ClickHouse Cloud.
Именованные коллекции можно настраивать с помощью DDL или в файлах конфигурации; они применяются при запуске ClickHouse. Они упрощают создание объектов и позволяют скрывать учетные данные от пользователей без административного доступа. Ключи в именованной коллекции должны совпадать с именами параметров соответствующей функции, движка таблицы, базы данных и т. д. В примерах ниже для каждого типа приведена ссылка на список параметров. Чтобы переопределить параметр, сохранённый в именованной коллекции, требуется привилегия SHOW NAMED COLLECTIONS SECRETS на эту коллекцию — даже если параметр помечен как OVERRIDABLE. Ключи, помеченные NOT OVERRIDABLE в SQL или overridable="false" в XML, переопределить нельзя. Для добавления параметра, которого нет в коллекции, эта дополнительная привилегия не требуется. Псевдонимы, например addresses_expr для host, считаются переопределением сохранённого параметра.
Для этой проверки нужна только привилегия; она не зависит от настроек, управляющих отображением секретов. Настройка allow_named_collection_override_by_default устарела и ни на что не влияет. Для источников словарей действует то же правило. Привилегия проверяется при создании, подключении или восстановлении словаря. При загрузке словаря принудительно применяются только ключи, помеченные как NOT OVERRIDABLE.

Хранение именованных коллекций в системной базе данных

Пример DDL

В приведённом выше примере:
  • key_1 могут переопределять пользователи, имеющие привилегию SHOW NAMED COLLECTIONS SECRETS для этой коллекции.
  • key_2 нельзя переопределить никогда.
  • url могут переопределять пользователи, имеющие привилегию SHOW NAMED COLLECTIONS SECRETS для этой коллекции.

Разрешения на создание именованных коллекций с помощью DDL

Чтобы управлять именованными коллекциями с помощью DDL, пользователь должен иметь привилегию named_collection_control. Ее можно назначить, добавив файл в /etc/clickhouse-server/users.d/. В этом примере пользователю default назначаются привилегии access_management и named_collection_control:
/etc/clickhouse-server/users.d/user_default.xml
В приведённом выше примере значение password_sha256_hex — это шестнадцатеричное представление SHA256-хеша пароля. В этой конфигурации для пользователя default задан атрибут replace=true, поскольку в конфигурации по умолчанию установлен password в открытом виде, а для одного пользователя нельзя одновременно задать пароль в открытом виде и пароль в формате SHA256 hex.
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, также нужно указать path (путь в ZooKeeper/Keeper, где будут храниться именованные коллекции) в разделе named_collections_storage файла конфигурации. В следующем примере используются шифрование и ZooKeeper/Keeper:
Необязательный параметр конфигурации update_timeout_ms по умолчанию имеет значение 5000. Проверить активный тип хранилища можно с помощью system.server_settings и getServerSetting:
Изменение типа хранилища требует перезапуска сервера; SYSTEM RELOAD CONFIG не изменяет активное backend-соединение.

Хранение именованных коллекций в конфигурационных файлах

Пример XML

/etc/clickhouse-server/config.d/named_collections.xml
В приведённом выше примере:
  • key_1 могут переопределить пользователи с привилегией SHOW NAMED COLLECTIONS SECRETS на эту коллекцию.
  • key_2 нельзя переопределить никогда.
  • url могут переопределить пользователи с привилегией SHOW NAMED COLLECTIONS SECRETS на эту коллекцию.

Изменение именованных коллекций

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

Изменить именованную DDL-коллекцию

Измените или добавьте ключи key1 и key3 в коллекции collection2 (это не изменит значение флага overridable для этих ключей):
Измените или добавьте ключ key1 и разрешите всегда его переопределять:
Удалите ключ key2 из коллекции collection2:
Измените или добавьте ключ key1, а также удалите ключ key3 в коллекции collection2:
Чтобы принудительно применить к ключу настройки по умолчанию для флага overridable, необходимо удалить ключ и добавить его заново.

Удалите именованную коллекцию DDL collection2:

Именованные коллекции для доступа к S3

Описание параметров см. в разделе табличной функции S3.

Пример DDL

Пример XML

Примеры использования именованной коллекции в функции s3() и таблице S3

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

Функция s3()

Первый аргумент функции s3(), показанной выше, — это имя коллекции s3_mydata. Без именованных коллекций идентификатор ключа доступа, секретный ключ, формат и URL пришлось бы указывать при каждом вызове функции s3().

Таблица S3

Именованные коллекции для доступа к базе данных MySQL

Описание параметров см. на странице mysql.

Пример DDL

Пример XML

Примеры для функции mysql(), таблицы MySQL, базы данных MySQL и именованной коллекции словарь

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

Функция mysql()

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

Таблица MySQL

DDL переопределяет параметр connection_pool_size в именованной коллекции.

База данных MySQL

Словарь MySQL

Именованные коллекции для доступа к базе данных PostgreSQL

Описание параметров см. в postgresql. Также доступны следующие псевдонимы:
  • username для user
  • db для database.
Настройки пула соединений для движка таблицы PostgreSQL (postgresql_connection_pool_size и другие настройки postgresql_*) также можно хранить в коллекции или передавать в виде переопределений key = value. Они применяются к движку таблицы PostgreSQL, табличной функции postgresql и движку базы данных PostgreSQL; явная секция SETTINGS для таблицы имеет приоритет над значениями из коллекции. Параметр addresses_expr используется в коллекции вместо host:port. Этот параметр необязателен, поскольку есть и другие необязательные параметры: host, hostname, port. Приоритет показан в следующем псевдокоде:
Пример создания:
Пример конфигурации:

Пример использования именованных коллекций с функцией postgresql

Пример использования именованных коллекций с базой данных на движке PostgreSQL

PostgreSQL копирует данные из именованной коллекции при создании таблицы. Изменения в коллекции не влияют на уже существующие таблицы.

Пример использования именованных коллекций с базой данных на движке PostgreSQL

Пример использования именованных коллекций со словарём на основе источника POSTGRESQL

Именованные коллекции для доступа к удалённой базе данных ClickHouse

Описание параметров приведено в remote. Пример конфигурации:
secure не нужен для подключения, так как используется remoteSecure, но его можно использовать для словарей.

Пример использования именованных коллекций в функциях remote/remoteSecure

Пример использования именованных коллекций со словарём на основе ClickHouse

Именованные коллекции для доступа к Kafka

Описание параметров приведено в разделе Kafka.

Пример DDL

Пример XML

Аутентификация OAUTHBEARER/OIDC

Параметры OAUTHBEARER относятся к расширенным настройкам librdkafka, поэтому их необходимо размещать внутри <kafka> в каждой именованной коллекции. Ключи верхнего уровня kafka_* задают настройки движка таблицы Kafka. Перед передачей в librdkafka ClickHouse заменяет символы подчёркивания в именах вложенных XML-элементов на точки. В следующем примере настраиваются учётные данные клиента OAuth для пространства имен Azure Event Hubs:
/etc/clickhouse-server/config.d/named_collections.xml
Если в ENGINE = Kafka(eventhub_one) используется именованная коллекция, ClickHouse не объединяет её с глобальной конфигурацией сервера <kafka>. Если адрес брокера или область действия (scope) OAuth различаются, создайте отдельную коллекцию для каждого пространства имен Event Hubs и укажите в ней все обязательные параметры OIDC. Атрибуты from_env в этом примере применяются к именованным коллекциям, определённым в XML, и считывают значения из окружения процесса сервера ClickHouse. Подробнее о развертывании и значениях по умолчанию см. в разделе подстановка из переменных окружения, а о защите секретов в предварительно обработанных файлах конфигурации — в разделе шифрование и скрытие конфигурации.

Пример использования именованных коллекций с таблицей Kafka

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

Именованные коллекции для резервных копий

Описание параметров см. в разделе Резервное копирование и восстановление.

Пример DDL

Пример XML

Именованные коллекции для доступа к таблице и словарю MongoDB

См. описание параметров в mongodb.

Пример DDL

Пример XML

Таблица MongoDB

DDL переопределяет настройку options в named collection.

Словарь MongoDB

Словарь использует коллекцию my_collection, указанную в именованной коллекции. Чтобы использовать другую коллекцию MongoDB, определите отдельную именованную коллекцию с соответствующим значением.