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

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

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', чтобы выбрать другую коллекцию.