Перейти к основному содержимому
Перейти к основному содержимому

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

Not supported in ClickHouse Cloud

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

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

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

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

предупреждение

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

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

Пример DDL​

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

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

подсказка

В приведенном выше примере значение password_sha256_hex является шестнадцатеричным представлением SHA256-хеша пароля. Эта настройка для пользователя default имеет атрибут replace=true, так как в конфигурации по умолчанию установлен открытый текстовый password, и невозможно установить как открытый текст, так и sha256 hex пароли для пользователя.

Хранение именованных коллекций​

Именованные коллекции могут храниться либо на локальном диске, либо в 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.

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

Пример XML​

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

  • key_1 всегда может быть переопределен.
  • key_2 никогда не может быть переопределен.
  • url может быть переопределен или нет, в зависимости от значения allow_named_collection_override_by_default.

Модификация именованных коллекций​

Именованные коллекции, созданные с помощью 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.

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

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

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

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

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

примечание

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

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

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

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

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

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

secure не нужен для подключения из-за remoteSecure, но может использоваться для словарей.

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

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

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

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

Пример DDL​

Пример XML​

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

Оба следующих примера используют одну и ту же именованную коллекцию my_kafka_cluster:

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

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

Пример DDL​

Пример XML​

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

Для описания параметров см. mongodb.

Пример DDL​

Пример XML​

Таблица MongoDB​

примечание

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

Словарь MongoDB​

примечание

Именованная коллекция указывает my_collection для имени коллекции. В вызове функции она переопределяется collection = 'my_dict' для выбора другой коллекции.