Подключение внешних словарей в Managed Service for ClickHouse®
Вы можете подключать к кластеру внешние словари и отключать их. Подробнее о словарях читайте в документации ClickHouse®
Managed Service for ClickHouse® поддерживает несколько типов источников словарей:
- ClickHouse®;
- HTTP(s);
- MongoDB;
- MySQL;
- PostgreSQL.
Словарями можно управлять либо через SQL, либо через интерфейсы облака. SQL — рекомендуемый способ.
Важно
Изменение настроек словарей приводит к перезапуску серверов ClickHouse® на хостах кластера.
Получить список словарей
- В консоли управления
перейдите на страницу каталога и выберите сервис Managed Service for ClickHouse. - Нажмите на имя нужного кластера и выберите вкладку Словари.
Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.
По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name
или --folder-id
.
Чтобы подключить внешний словарь к кластеру ClickHouse®:
-
Посмотрите описание команды CLI для получения детальной информации о кластере:
yc managed-clickhouse cluster get --help
-
Выполните команду:
yc managed-clickhouse cluster get <имя_кластера>
Подключенные словари отображаются в блоке dictionaries:
результата выполнения команды.
Чтобы просмотреть список словарей, воспользуйтесь методом REST API get для ресурса Cluster или вызовом gRPC API ClusterService/Get.
- Подключитесь к нужной базе данных кластера Managed Service for ClickHouse® с помощью
clickhouse-client
. - Выполните запрос
SHOW DICTIONARIES
.
Подключить словарь
Важно
Если словарь добавлен через консоль, для него недоступно управление через SQL.
- В консоли управления
перейдите на страницу каталога и выберите сервис Managed Service for ClickHouse. - Нажмите на имя нужного кластера и выберите вкладку Словари.
- В правом верхнем углу экрана нажмите Добавить словарь.
- Укажите настройки словаря и нажмите Сохранить.
Важно
Если словарь добавлен через CLI, для него недоступно управление через SQL.
Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.
По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name
или --folder-id
.
Чтобы подключить внешний словарь к кластеру ClickHouse®:
-
Посмотрите описание команды CLI для добавления словарей:
yc managed-clickhouse cluster add-external-dictionary --help
-
Выполните команду добавления словаря и укажите его настройки:
yc managed-clickhouse cluster add-external-dictionary \ --name=<имя_кластера_ClickHouse®> \ --dict-name=<имя_словаря> \ ...
Важно
Если словарь добавлен через API, для него недоступно управление через SQL.
Чтобы подключить словарь, воспользуйтесь методом REST API createExternalDictionary для ресурса Cluster или вызовом gRPC API ClusterService/CreateExternalDictionary.
Важно
Если словарь добавлен через SQL, для него недоступно управление через консоль, CLI и API.
-
Подключитесь к нужной базе данных кластера Managed Service for ClickHouse® с помощью
clickhouse-client
. -
Выполните DDL-запрос
и укажите настройки словаря:CREATE DICTIONARY <имя_словаря>( <столбцы_данных> ) PRIMARY KEY <имя_столбца_с_ключами> SOURCE(<источник>(<конфигурация_источника>)) LIFETIME(<интервал_обновления>) LAYOUT(<способ_размещения_в_памяти>());
Удалить словарь
- В консоли управления
перейдите на страницу каталога и выберите сервис Managed Service for ClickHouse. - Нажмите на имя нужного кластера и выберите вкладку Словари.
- Нажмите на значок
в строке нужного словаря и выберите пункт Удалить словарь.
Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.
По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name
или --folder-id
.
Чтобы удалить внешний словарь:
-
Посмотрите описание команды CLI для удаления словаря:
yc managed-clickhouse cluster remove-external-dictionary --help
-
Удалите словарь с помощью команды:
yc managed-clickhouse cluster remove-external-dictionary \ --name=<имя_кластера> \ --dict-name=<имя_словаря>
Чтобы удалить словарь, воспользуйтесь методом REST API deleteExternalDictionary для ресурса Cluster или вызовом gRPC API ClusterService/DeleteExternalDictionary.
- Подключитесь к нужной базе данных кластера Managed Service for ClickHouse® с помощью
clickhouse-client
. - Выполните запрос
DROP DICTIONARY <имя_БД>.<имя_словаря>
.
Настройки словарей
SQL
<имя_словаря>
— имя нового словаря.<столбцы_данных>
— список столбцов с данными словаря и их тип.PRIMARY KEY
— имя ключевого столбца словаря.SOURCE
— источник и его параметры.LIFETIME
— периодичность обновления словаря.LAYOUT
— способ размещения словаря в памяти. Поддерживаются способы:flat
,hashed
,cache
,range_hashed
,complex_key_hashed
,complex_key_cache
.
Подробные описание настроек читайте в документации ClickHouse®
Консоль управления
- Имя — имя нового словаря.
Источник
- Хост — имя хоста источника. Хост должен находиться в той же сети, что и кластер ClickHouse®.
- Порт — порт для подключения к источнику.
- Пользователь — имя пользователя базы данных источника.
- Пароль — пароль для доступа к базе данных источника.
- База данных — имя базы данных источника.
- Таблица — имя таблицы источника.
- Условие выбора — условие для выбора строк, из которых будет сформирован словарь. Например, условие выбора
id=10
эквивалентно SQL-командеWHERE id=10
. - (Опционально) Проверка статуса словаря — SQL-запрос для проверки изменений словаря. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса.
Подробнее читайте в документации ClickHouse® .
- URL — URL HTTP(s)-источника.
- Формат файла — формат
файла для HTTP(s)-источника. Подробнее о форматах читайте в документации ClickHouse® .
- Хост — имя хоста источника. Хост должен находиться в той же сети, что и кластер ClickHouse®.
- Порт — порт для подключения к источнику.
- Пользователь — имя пользователя базы данных источника.
- Пароль — пароль для доступа к базе данных источника.
- База данных — имя базы данных источника.
- Коллекция — имя коллекции источника.
- Реплики — список реплик MySQL, которые будут использоваться как источник словаря.
Для реплик можно задать общие параметры подключения или настроить порт, имя пользователя и пароль. - Порт — порт для подключения к источнику.
- Пользователь — имя пользователя базы данных источника.
- Пароль — пароль для доступа к базе данных источника.
- База данных — имя базы данных источника.
- Таблица — имя таблицы источника.
- Условие выбора — условие для выбора строк, из которых будет сформирован словарь. Например, условие выбора
id=10
эквивалентно SQL-командеWHERE id=10
. - (Опционально) Проверка статуса словаря — SQL-запрос для проверки изменений словаря. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса.
Подробнее читайте в документации ClickHouse® .
- Хосты — имена хоста PostgreSQL и его реплик, которые будут использоваться в качестве источника словаря. Хосты должны находиться в той же сети, что и кластер ClickHouse®.
- Порт — порт для подключения к источнику.
- Пользователь — имя пользователя базы данных источника.
- Пароль — пароль для доступа к базе данных источника.
- База данных — имя базы данных источника.
- Таблица — имя таблицы источника.
- (Опционально) Проверка статуса словаря — SQL-запрос для проверки изменений словаря. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса.
Подробнее читайте в документации ClickHouse® . - SSL mode — режим для установки защищенного SSL TCP/IP соединения с базой данных PostgreSQL.
Подробнее читайте в документации PostgreSQL .
Подробнее об источниках словарей и параметрах их подключения читайте в документации ClickHouse®
Способ размещения в памяти
-
Размещение в памяти — способ размещения словаря в памяти. Поддерживаются способы:
flat
,hashed
,cache
,range_hashed
,complex_key_hashed
,complex_key_cache
. Подробнее о способах размещения словарей в памяти читайте в документации ClickHouse® . -
Размер кэша — количество ячеек кэша для способов
cache
,complex_key_cache
. Подробнее о кэше читайте в документации ClickHouse® . -
Числовой ключ — имя ключевого столбца словаря. Ключевой столбец должен иметь тип данных UInt64. Используется для способов
flat
,hashed
,cache
,range_hashed
. Подробнее о ключах читайте в документации ClickHouse® . -
Столбцы данных — список столбцов с данными словаря:
- Имя — имя столбца.
- Тип данных — тип данных столбца.
- (Опционально) Значение по умолчанию — значение по умолчанию для пустого элемента. При загрузке словаря все пустые элементы будут заменены на это значение. Нельзя указать значение
NULL
. - (Опционально) Выражение — выражение
, которое ClickHouse® выполняет со значением столбца. - Иерархический — признак поддержки иерархии.
- Инъективный — признак инъективности отображения
id
→attribute
.
Подробнее о параметрах столбцов читайте в документации ClickHouse®
Частота обновления
-
Период — задайте периодичность обновления словаря:
-
фиксированный — фиксированный период между обновлениями словаря:
- Длительность периода — период обновления данных словаря в секундах.
-
переменный — диапазон, внутри которого ClickHouse® случайно выберет время для обновления. Это поможет распределить нагрузку на источник словаря при обновлении на большом количестве серверов:
- Минимум — минимальное значение периода между обновлениями словаря в секундах.
- Максимум — максимальное значение периода между обновлениями словаря в секундах.
-
Подробнее об обновлении словарей читайте в документации ClickHouse®
CLI
--dict-name
— имя нового словаря.
-
--clickhouse-source
— настройки источника ClickHouse®:db
— имя базы данных источника.table
— имя таблицы источника.host
— имя хоста источника. Хост должен находиться в той же сети, что и кластер ClickHouse®.port
— порт для подключения к источнику.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.where
— условие для выбора строк, из которых будет сформирован словарь. Например, условие выбораid=10
эквивалентно SQL-командеWHERE id=10
.
--http-source-url
— URL HTTP(s)-источника.--http-source-format
— формат файла для HTTP(s)-источника. Подробнее о форматах читайте в документации ClickHouse® .
-
--mongodb-source
— настройки источника MongoDB:db
— имя базы данных источника.connection
— имя коллекции для MongoDB-источника.host
— имя хоста источника. Хост должен находиться в той же сети, что и кластер ClickHouse®.port
— порт для подключения к источнику.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.
-
--mysql-source
— настройки источника MySQL:db
— имя базы данных источника.table
— имя таблицы источника.port
— порт для подключения к источнику.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.where
— условие для выбора строк, из которых будет сформирован словарь. Например, условие выбораid=10
эквивалентно SQL-командеWHERE id=10
.
-
--mysql-replica
— настройки реплик источника MySQL:host
— имя хоста реплики.priority
— приоритет реплики. При попытке соединения ClickHouse® обходит реплики в соответствии с приоритетом. Чем меньше цифра, тем выше приоритет.port
— порт для подключения к реплике.user
— имя пользователя базы данных.password
— пароль для доступа к базе данных.
-
--mysql-invalidate-query
— запрос для проверки изменений словаря. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса.
-
--postgresql-source
— настройки источника PostgreSQL:db
— имя базы данных источника.table
— имя таблицы источника.port
— порт для подключения к источнику.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.ssl-mode
— режим для установки защищенного SSL TCP/IP соединения с базой данных PostgreSQL. Допустимые значения:disable
,allow
,prefer
,verify-ca
,verify-full
.
-
--postgresql-source-hosts
— имена хоста PostgreSQL и его реплик, которые будут использоваться в качестве источника словаря. Хосты должны находиться в той же сети, что и кластер ClickHouse®. -
--postgresql-invalidate-query
— запрос для проверки изменений словаря. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса.
-
--structure-id
— имя ключевого столбца словаря. Ключевой столбец должен иметь тип данных UInt64. Используется для способовflat
,hashed
,cache
,range_hashed
. Подробнее о ключах читайте в документации ClickHouse® . -
--structure-key
— список столбцов с данными словаря:name
— имя столбца.type
— тип данных столбца.null-value
— значение по умолчанию для пустого элемента. При загрузке словаря все пустые элементы будут заменены на это значение. Нельзя указать значениеNULL
.expression
— выражение , которое ClickHouse® выполняет со значением столбца.hierarchical
— признак поддержки иерархии.injective
— признак инъективности отображенияid
→attribute
.
-
--structure-attribute
— описание полей, доступных для запросов к базе данных:name
— имя столбца.type
— тип данных столбца.null-value
— значение по умолчанию для пустого элемента. При загрузке словаря все пустые элементы будут заменены на это значение. Нельзя указать значениеNULL
.expression
— выражение , которое ClickHouse® выполняет со значением столбца.hierarchical
— признак поддержки иерархии.injective
— признак инъективности отображенияid
→attribute
.
-
--fixed-lifetime
— фиксированный период между обновлениями словаря в секундах. -
--lifetime-range
— диапазон, внутри которого ClickHouse® случайно выберет время для обновления. Это поможет распределить нагрузку на источник словаря при обновлении на большом количестве серверов.min
— минимальное значение периода между обновлениями словаря в секундах.max
— максимальное значение периода между обновлениями словаря в секундах.
-
--layout-type
— способ размещения словаря в памяти. Поддерживаются способы:flat
,hashed
,cache
,range_hashed
,complex_key_hashed
,complex_key_cache
. Подробнее о способах размещения словарей в памяти читайте в документации ClickHouse® . -
--layout-size-in-cells
— количество ячеек кэша для способовcache
,complex_key_cache
. Подробнее о кэше читайте в документации ClickHouse® .
API
Описание настроек приведены на странице описания метода API createExternalDictionary.
Примеры
Подключите словарь с тестовыми характеристиками:
-
кластер
mych
; -
имя
mychdict
; -
имя ключевого столбца
id
; -
поля, доступные для запросов к базе данных:
id
с типомUInt64
;field1
с типомString
;
-
фиксированный период между обновлениями словаря 300 секунд;
-
способ размещения словаря в памяти
cache
; -
источник PostgreSQL:
- база данных
db1
; - имя таблицы
table
; - порт для подключения
5432
; - имя пользователя базы данных
user1
; - пароль для доступа к базе данных
user1user1
; - режим для установки защищенного SSL TCP/IP соединения с базой данных
verify-full
;
- база данных
-
имя хоста
rc1b-05vjbfhf********.mdb.yandexcloud.net
.
Выполните следующую команду:
yc managed-clickhouse cluster add-external-dictionary \
--name=mych \
--dict-name=mychdict \
--structure-id=id \
--structure-attribute name=id,`
`type=UInt64,`
`name=field1,`
`type=String \
--fixed-lifetime=300 \
--layout-type=cache \
--postgresql-source db=db1,`
`table=table,`
`port=5432,`
`user=user1,`
`password=user1user1,`
`ssl-mode=verify-full \
--postgresql-source-hosts=rc1b-05vjbfhf********.mdb.yandexcloud.net
ClickHouse® является зарегистрированным товарным знаком ClickHouse, Inc