Подключение внешних словарей в Managed Service for ClickHouse®
Вы можете подключать к кластеру внешние словари и отключать их. Подробнее о словарях читайте в документации ClickHouse®
Managed Service for ClickHouse® поддерживает несколько типов источников словарей:
- ClickHouse®;
- HTTP(s);
- MongoDB;
- MySQL®;
- PostgreSQL.
Словарями можно управлять либо через SQL (рекомендуемый способ), либо через интерфейсы Yandex Cloud.
Важно
Изменение настроек словарей приводит к перезапуску серверов 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:
результата выполнения команды.
-
Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
export IAM_TOKEN="<IAM-токен>"
-
Воспользуйтесь методом Cluster.listExternalDictionaries и выполните запрос, например, с помощью cURL
:curl \ --request GET \ --header "Authorization: Bearer $IAM_TOKEN" \ --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<идентификатор_кластера>/externalDictionaries'
Идентификатор кластера можно запросить со списком кластеров в каталоге.
-
Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
-
Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
export IAM_TOKEN="<IAM-токен>"
-
Клонируйте репозиторий cloudapi
:cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
Далее предполагается, что содержимое репозитория находится в директории
~/cloudapi/
. -
Воспользуйтесь вызовом ClusterService/ListExternalDictionaries и выполните запрос, например, с помощью gRPCurl
:grpcurl \ -format json \ -import-path ~/cloudapi/ \ -import-path ~/cloudapi/third_party/googleapis/ \ -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/cluster_service.proto \ -rpc-header "Authorization: Bearer $IAM_TOKEN" \ -d '{ "cluster_id": "<идентификатор_кластера>" }' \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.ListExternalDictionaries
Идентификатор кластера можно запросить со списком кластеров в каталоге.
-
Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
- Подключитесь к нужной базе данных кластера 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.
Чтобы создать внешний словарь в кластере ClickHouse®:
-
Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
export IAM_TOKEN="<IAM-токен>"
-
Воспользуйтесь методом Cluster.createExternalDictionary и выполните запрос, например, с помощью cURL
:-
Создайте файл
body.json
и добавьте в него следующее содержимое:{ "externalDictionary": { "name": "<имя_словаря>", "structure": { "id": { "name": "<имя_ключевого_столбца_словаря>" }, "key": { "attributes": [ <массив_столбцов_с_данными_словаря> ] }, "rangeMin": {<начальный_столбец_для_RANGE_HASHED>}, "rangeMax": {<конечный_столбец_для_RANGE_HASHED>}, "attributes": [ <массив_описаний_полей> ] }, "layout": {<способ_размещения_в_памяти>}, "fixedLifetime": "<фиксированный_период_между_обновлениями>", "lifetimeRange": {<диапазон_для_выбора_периода_между_обновлениями>}, "httpSource": {<настройки_источника_HTTP(s)>}, "mysqlSource": {<настройки_источника_MySQL®>}, "clickhouseSource": {<настройки_источника_ClickHouse®>}, "mongodbSource": {<настройки_источника_MongoDB>}, "postgresqlSource": {<настройки_источника_PostgreSQL>} } }
Где:
-
externalDictionary.name
— имя словаря. -
externalDictionary.structure
— структура словаря:id.name
— имя ключевого столбца словаря.key.attributes
— массив для описания составного ключа словаря.rangeMin
— описание начального столбца, которое необходимо, если используется способ размещения в памятиRANGE_HASHED
.rangeMax
— описание конечного столбца, которое необходимо, если используется способ размещения в памятиRANGE_HASHED
.attributes
— массив описаний полей, доступных для запросов к базе данных.
Важно
Поля
structure.id.name
иstructure.key.attributes
— взаимоисключающие. Использование одного делает невозможным использование другого. -
externalDictionary.layout
— способ размещения словаря в памяти. -
externalDictionary.fixedLifetime
— фиксированный период между обновлениями словаря в секундах. -
externalDictionary.lifetimeRange
— диапазон, внутри которого ClickHouse® случайно выберет время для обновления. Это поможет распределить нагрузку на источник словаря при обновлении на большом количестве серверов.Важно
Поля
fixedLifetime
иlifetimeRange
— взаимоисключающие. Использование одного делает невозможным использование другого. -
externalDictionary.***Source
— настройки источника данных для словаря. Выберите один из источников и укажите его настройки:httpSource
— источник HTTP(s).mysqlSource
— источник MySQL®.clickhouseSource
— источник ClickHouse®.mongodbSource
— источник MongoDB.postgresqlSource
— источник PostgreSQL.
Подробное описание атрибутов и других настроек словаря приведено ниже.
-
-
Выполните запрос:
curl \ --request POST \ --header "Authorization: Bearer $IAM_TOKEN" \ --header "Content-Type: application/json" \ --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<идентификатор_кластера>:createExternalDictionary' \ --data '@body.json'
Идентификатор кластера можно запросить со списком кластеров в каталоге.
-
-
Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
Важно
Если словарь добавлен через API, для него недоступно управление через SQL.
Чтобы создать внешний словарь в кластере ClickHouse®:
-
Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
export IAM_TOKEN="<IAM-токен>"
-
Клонируйте репозиторий cloudapi
:cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
Далее предполагается, что содержимое репозитория находится в директории
~/cloudapi/
. -
Воспользуйтесь вызовом ClusterService/CreateExternalDictionary и выполните запрос, например, с помощью gRPCurl
:-
Создайте файл
body.json
и добавьте в него следующее содержимое:{ "cluster_id": "<идентификатор_кластера>", "external_dictionary": { "name": "<имя_словаря>", "structure": { "id": { "name": "<имя_ключевого_столбца_словаря>" }, "key": { "attributes": [<массив_столбцов_с_данными_словаря>] }, "range_min": {<начальный_столбец_для_RANGE_HASHED>}, "range_max": {<конечный_столбец_для_RANGE_HASHED>}, "attributes": [<массив_описаний_полей>] }, "layout": {<способ_размещения_в_памяти>}, "fixed_lifetime": "<фиксированный_период_между_обновлениями>", "lifetime_range": {<диапазон_для_выбора_периода_между_обновлениями>}, "http_source": {<настройки_источника_HTTP(s)>}, "mysql_source": {<настройки_источника_MySQL>}, "clickhouse_source": {<настройки_источника_ClickHouse®>}, "mongodb_source": {<настройки_источника_MongoDB>}, "postgresql_source": {<настройки_источника_PostgreSQL>} } }
Где:
-
external_dictionary.name
— имя словаря. -
external_dictionary.structure
— структура словаря:id.name
— имя ключевого столбца словаря.key.attributes
— массив описаний столбцов с данными словаря.range_min
— описание начального столбца, которое необходимо, если используется способ размещения в памятиRANGE_HASHED
.range_max
— описание конечного столбца, которое необходимо, если используется способ размещения в памятиRANGE_HASHED
.attributes
— массив описаний полей, доступных для запросов к базе данных.
Важно
Поля
structure.id.name
иstructure.key.attributes
— взаимоисключающие. Использование одного делает невозможным использование другого. -
external_dictionary.layout
— способ размещения словаря в памяти. -
external_dictionary.fixed_lifetime
— фиксированный период между обновлениями словаря в секундах. -
external_dictionary.lifetime_range
— диапазон, внутри которого ClickHouse® случайно выберет время для обновления. Это поможет распределить нагрузку на источник словаря при обновлении на большом количестве серверов.Важно
Поля
fixed_lifetime
иlifetime_range
— взаимоисключающие. Использование одного делает невозможным использование другого. -
external_dictionary.***_source
— настройки источника данных для словаря. Выберите один из источников и укажите его настройки:http_source
— источник HTTP(s).mysql_source
— источник MySQL®.clickhouse_source
— источник ClickHouse®.mongodb_source
— источник MongoDB.postgresql_source
— источник PostgreSQL.
Подробное описание атрибутов и других настроек словаря приведено ниже.
Идентификатор кластера можно запросить со списком кластеров в каталоге.
-
-
Выполните запрос:
grpcurl \ -format json \ -import-path ~/cloudapi/ \ -import-path ~/cloudapi/third_party/googleapis/ \ -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/cluster_service.proto \ -rpc-header "Authorization: Bearer $IAM_TOKEN" \ -d @ \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.CreateExternalDictionary \ < body.json
-
-
Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
Важно
Если словарь добавлен через SQL, для него недоступно управление через консоль, CLI и API.
-
Подключитесь к нужной базе данных кластера Managed Service for ClickHouse® с помощью
clickhouse-client
. -
Выполните DDL-запрос
:CREATE DICTIONARY <имя_словаря>( <столбцы_данных> ) PRIMARY KEY <имя_столбца_с_ключами> SOURCE(<источник>(<конфигурация_источника>)) LIFETIME(<интервал_обновления>) LAYOUT(<способ_размещения_в_памяти>());
Где:
<имя_словаря>
— имя нового словаря.<столбцы_данных>
— список столбцов с данными словаря и их тип.PRIMARY KEY
— имя ключевого столбца словаря.SOURCE
— источник и его параметры.LIFETIME
— периодичность обновления словаря.LAYOUT
— способ размещения словаря в памяти. Поддерживаются способы:flat
,hashed
,cache
,range_hashed
,complex_key_hashed
,complex_key_cache
.
Подробное описание настроек читайте в документации ClickHouse®
Обновить словарь
-
Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
export IAM_TOKEN="<IAM-токен>"
-
Воспользуйтесь методом Cluster.updateExternalDictionary и выполните запрос, например, с помощью cURL
:-
Создайте файл
body.json
и добавьте в него следующее содержимое:{ "externalDictionary": { "name": "<имя_словаря>", "structure": { "id": { "name": "<имя_ключевого_столбца_словаря>" }, "key": { "attributes": [ <массив_столбцов_с_данными_словаря> ] }, "rangeMin": {<начальный_столбец_для_RANGE_HASHED>}, "rangeMax": {<конечный_столбец_для_RANGE_HASHED>}, "attributes": [ <массив_описаний_полей> ] }, "layout": {<способ_размещения_в_памяти>}, "fixedLifetime": "<фиксированный_период_между_обновлениями>", "lifetimeRange": {<диапазон_для_выбора_периода_между_обновлениями>}, "httpSource": {<настройки_источника_HTTP(s)>}, "mysqlSource": {<настройки_источника_MySQL®>}, "clickhouseSource": {<настройки_источника_ClickHouse®>}, "mongodbSource": {<настройки_источника_MongoDB>}, "postgresqlSource": {<настройки_источника_PostgreSQL>} }, "updateMask": "externalDictionary.<настройка_1>,...,externalDictionary.<настройка_N>" }
Где:
-
updateMask
— перечень изменяемых параметров в одну строку через запятую.В данном случае перечислите все изменяемые настройки словаря.
-
externalDictionary.name
— имя словаря. -
externalDictionary.structure
— структура словаря:id.name
— имя ключевого столбца словаря.key.attributes
— массив для описания составного ключа словаря.rangeMin
— описание начального столбца, которое необходимо, если используется способ размещения в памятиRANGE_HASHED
.rangeMax
— описание конечного столбца, которое необходимо, если используется способ размещения в памятиRANGE_HASHED
.attributes
— массив описаний полей, доступных для запросов к базе данных.
Важно
Поля
structure.id.name
иstructure.key.attributes
— взаимоисключающие. Использование одного делает невозможным использование другого. -
externalDictionary.layout
— способ размещения словаря в памяти. -
externalDictionary.fixedLifetime
— фиксированный период между обновлениями словаря в секундах. -
externalDictionary.lifetimeRange
— диапазон, внутри которого ClickHouse® случайно выберет время для обновления. Это поможет распределить нагрузку на источник словаря при обновлении на большом количестве серверов.Важно
Поля
fixedLifetime
иlifetimeRange
— взаимоисключающие. Использование одного делает невозможным использование другого. -
externalDictionary.***Source
— настройки источника данных для словаря. Выберите один из источников и укажите его настройки:httpSource
— источник HTTP(s).mysqlSource
— источник MySQL®.clickhouseSource
— источник ClickHouse®.mongodbSource
— источник MongoDB.postgresqlSource
— источник PostgreSQL.
Подробное описание атрибутов и других настроек словаря приведено ниже.
-
-
Выполните запрос:
curl \ --request POST \ --header "Authorization: Bearer $IAM_TOKEN" \ --header "Content-Type: application/json" \ --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<идентификатор_кластера>:updateExternalDictionary' \ --data '@body.json'
Идентификатор кластера можно запросить со списком кластеров в каталоге.
-
-
Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
-
Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
export IAM_TOKEN="<IAM-токен>"
-
Клонируйте репозиторий cloudapi
:cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
Далее предполагается, что содержимое репозитория находится в директории
~/cloudapi/
. -
Воспользуйтесь вызовом ClusterService/UpdateExternalDictionary и выполните запрос, например, с помощью gRPCurl
:-
Создайте файл
body.json
и добавьте в него следующее содержимое:{ "cluster_id": "<идентификатор_кластера>", "external_dictionary": { "name": "<имя_словаря>", "structure": { "id": { "name": "<имя_ключевого_столбца_словаря>" }, "key": { "attributes": [<массив_столбцов_с_данными_словаря>] }, "range_min": {<начальный_столбец_для_RANGE_HASHED>}, "range_max": {<конечный_столбец_для_RANGE_HASHED>}, "attributes": [<массив_описаний_полей>] }, "layout": {<способ_размещения_в_памяти>}, "fixed_lifetime": "<фиксированный_период_между_обновлениями>", "lifetime_range": {<диапазон_для_выбора_периода_между_обновлениями>}, "http_source": {<настройки_источника_HTTP(s)>}, "mysql_source": {<настройки_источника_MySQL>}, "clickhouse_source": {<настройки_источника_ClickHouse®>}, "mongodb_source": {<настройки_источника_MongoDB>}, "postgresql_source": {<настройки_источника_PostgreSQL>} }, "update_mask": "externalDictionary.<настройка_1>,...,externalDictionary.<настройка_N>" }
Где:
-
update_mask
— перечень изменяемых параметров в одну строку через запятую.В данном случае перечислите все изменяемые настройки словаря.
-
external_dictionary.name
— имя словаря. -
external_dictionary.structure
— структура словаря:id.name
— имя ключевого столбца словаря.key.attributes
— массив описаний столбцов с данными словаря.range_min
— описание начального столбца, которое необходимо, если используется способ размещения в памятиRANGE_HASHED
.range_max
— описание конечного столбца, которое необходимо, если используется способ размещения в памятиRANGE_HASHED
.attributes
— массив описаний полей, доступных для запросов к базе данных.
Важно
Поля
structure.id.name
иstructure.key.attributes
— взаимоисключающие. Использование одного делает невозможным использование другого. -
external_dictionary.layout
— способ размещения словаря в памяти. -
external_dictionary.fixed_lifetime
— фиксированный период между обновлениями словаря в секундах. -
external_dictionary.lifetime_range
— диапазон, внутри которого ClickHouse® случайно выберет время для обновления. Это поможет распределить нагрузку на источник словаря при обновлении на большом количестве серверов.Важно
Поля
fixed_lifetime
иlifetime_range
— взаимоисключающие. Использование одного делает невозможным использование другого. -
external_dictionary.***_source
— настройки источника данных для словаря. Выберите один из источников и укажите его настройки:http_source
— источник HTTP(s).mysql_source
— источник MySQL®.clickhouse_source
— источник ClickHouse®.mongodb_source
— источник MongoDB.postgresql_source
— источник PostgreSQL.
Подробное описание атрибутов и других настроек словаря приведено ниже.
Идентификатор кластера можно запросить со списком кластеров в каталоге.
-
-
Выполните запрос:
grpcurl \ -format json \ -import-path ~/cloudapi/ \ -import-path ~/cloudapi/third_party/googleapis/ \ -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/cluster_service.proto \ -rpc-header "Authorization: Bearer $IAM_TOKEN" \ -d @ \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.UpdateExternalDictionary \ < body.json
-
-
Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
Удалить словарь
- В консоли управления
перейдите на страницу каталога и выберите сервис 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=<имя_словаря>
-
Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
export IAM_TOKEN="<IAM-токен>"
-
Воспользуйтесь методом Cluster.deleteExternalDictionary и выполните запрос, например, с помощью cURL
:curl \ --request POST \ --header "Authorization: Bearer $IAM_TOKEN" \ --header "Content-Type: application/json" \ --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<идентификатор_кластера>:deleteExternalDictionary' \ --data '{ "externalDictionaryName": "<имя_словаря>" }'
Где
externalDictionaryName
— имя словаря, который нужно удалить. Имя словаря можно запросить со списком внешних словарей в кластере.Идентификатор кластера можно запросить со списком кластеров в каталоге.
-
Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
-
Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
export IAM_TOKEN="<IAM-токен>"
-
Клонируйте репозиторий cloudapi
:cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
Далее предполагается, что содержимое репозитория находится в директории
~/cloudapi/
. -
Воспользуйтесь вызовом ClusterService/DeleteExternalDictionary и выполните запрос, например, с помощью gRPCurl
:grpcurl \ -format json \ -import-path ~/cloudapi/ \ -import-path ~/cloudapi/third_party/googleapis/ \ -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/cluster_service.proto \ -rpc-header "Authorization: Bearer $IAM_TOKEN" \ -d '{ "cluster_id": "<идентификатор_кластера>", "external_dictionary_name": "<имя_словаря>" }' \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.DeleteExternalDictionary
Где
external_dictionary_name
— имя словаря, который нужно удалить. Имя словаря можно запросить со списком внешних словарей в кластере.Идентификатор кластера можно запросить со списком кластеров в каталоге.
-
Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.
- Подключитесь к нужной базе данных кластера Managed Service for ClickHouse® с помощью
clickhouse-client
. - Выполните запрос
DROP DICTIONARY <имя_БД>.<имя_словаря>
.
Настройки словарей
-
Имя — имя нового словаря.
-
Источник — настройки источника словаря. Выберите один из перечисленных источников и укажите его настройки:
ClickHouse®
- Хост — имя хоста ClickHouse®. Хост должен находиться в той же сети, что и кластер ClickHouse®.
- Порт — порт для подключения к источнику.
- Пользователь — имя пользователя базы данных источника.
- Пароль — пароль для доступа к базе данных источника.
- База данных — имя базы данных источника.
- Таблица — имя таблицы источника.
- Условие выбора — условие для выбора строк, из которых будет сформирован словарь. Например, условие выбора
id=10
эквивалентно SQL-командеWHERE id=10
. - (Опционально) Проверка статуса словаря — SQL-запрос для проверки изменений словаря. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса.
MongoDB
- Хост — имя хоста MongoDB. Хост должен находиться в той же сети, что и кластер ClickHouse®.
- Порт — порт для подключения к источнику.
- Пользователь — имя пользователя базы данных источника.
- Пароль — пароль для доступа к базе данных источника.
- База данных — имя базы данных источника.
- Коллекция — имя коллекции MongoDB.
MySQL®
- Реплики — список реплик MySQL®, которые будут использоваться как источник словаря.
Для реплик можно задать общие параметры подключения или настроить порт, имя пользователя и пароль. - Порт — порт для подключения к источнику.
- Пользователь — имя пользователя базы данных источника.
- Пароль — пароль для доступа к базе данных источника.
- База данных — имя базы данных источника.
- Таблица — имя таблицы источника.
- Условие выбора — условие для выбора строк, из которых будет сформирован словарь. Например, условие выбора
id=10
эквивалентно SQL-командеWHERE id=10
. - (Опционально) Проверка статуса словаря — SQL-запрос для проверки изменений словаря. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса.
PostgreSQL
- Хосты — имена хоста-мастера PostgreSQL и его реплик, которые будут использоваться в качестве источника словаря. Хосты должны находиться в той же сети, что и кластер ClickHouse®.
- Порт — порт для подключения к источнику.
- Пользователь — имя пользователя базы данных источника.
- Пароль — пароль для доступа к базе данных источника.
- База данных — имя базы данных источника.
- Таблица — имя таблицы источника.
- (Опционально) Проверка статуса словаря — SQL-запрос для проверки изменений словаря. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса.
- SSL mode — режим для установки защищенного SSL TCP/IP соединения с базой данных PostgreSQL. Подробнее читайте в документации PostgreSQL
.
HTTP(s)
- URL — URL HTTP(s)-источника.
- Формат файла — формат
файла для HTTP(s)-источника. Подробнее о форматах читайте в документации ClickHouse® .
Подробнее об источниках словарей и параметрах их подключения читайте в документации 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® . -
Столбцы данных — описание составного ключа словаря. Составной ключ может состоять из одного или более элементов. Используется для способов
complex_key_hashed
,complex_key_cache
:- Имя — имя столбца.
- Тип данных — тип данных столбца.
- (Опционально) Значение по умолчанию — значение по умолчанию для пустого элемента. При загрузке словаря все пустые элементы будут заменены на это значение. Нельзя указать значение
NULL
. - (Опционально) Выражение — выражение
, которое ClickHouse® выполняет со значением столбца. - Иерархический — признак поддержки иерархии.
- Инъективный — признак инъективности отображения
id
→attribute
.
Подробнее о параметрах составного ключа читайте в документации ClickHouse®
. -
Размещение в памяти — настройки частоты обновления словаря:
-
Период — периодичность обновления словаря. Выберите тип периода обновления и его настройки:
-
фиксированный — фиксированный период между обновлениями словаря:
- Длительность периода — период обновления данных словаря в секундах.
-
переменный — диапазон, внутри которого ClickHouse® случайно выберет время для обновления. Это поможет распределить нагрузку на источник словаря при обновлении на большом количестве серверов:
- Минимум — минимальное значение периода между обновлениями словаря в секундах.
- Максимум — максимальное значение периода между обновлениями словаря в секундах.
-
Подробнее об обновлении словарей читайте в документации ClickHouse®
. -
-
--dict-name
— имя нового словаря. -
--***-source
— настройки источника словаря. Выберите один из перечисленных источников и укажите его настройки:--clickhouse-source
— источник ClickHouse®host
— имя хоста источника. Хост должен находиться в той же сети, что и кластер ClickHouse®.port
— порт для подключения к источнику.db
— имя базы данных источника.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.table
— имя таблицы источника.where
— условие для выбора строк, из которых будет сформирован словарь. Например, условие выбораid=10
эквивалентно SQL-командеWHERE id=10
.
--mongodb-source
— источник MongoDBhost
— имя хоста источника. Хост должен находиться в той же сети, что и кластер ClickHouse®.port
— порт для подключения к источнику.db
— имя базы данных источника.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.connection
— имя коллекции источника.
--mysql-source
– источник MySQL®db
— имя базы данных источника.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.table
— имя таблицы источника.where
— условие для выбора строк, из которых будет сформирован словарь. Например, условие выбораid=10
эквивалентно SQL-командеWHERE id=10
.
--postgresql-source
— источник PostgreSQLtable
— имя таблицы источника.ssl-mode
— режим для установки защищенного SSL TCP/IP соединения с базой данных PostgreSQL. Допустимые значения:disable
,allow
,prefer
,verify-ca
,verify-full
.
--http-source
– источник HTTP(s)url
— URL HTTP(s)-источника.format
— формат файла для HTTP(s)-источника. Подробнее о форматах читайте в документации ClickHouse® .
-
--mysql-replica
— настройки реплик источника MySQL®:host
— имя хоста реплики.priority
— приоритет реплики. При попытке соединения ClickHouse® обходит реплики в соответствии с приоритетом. Чем меньше цифра, тем выше приоритет.port
— порт для подключения к реплике.user
— имя пользователя базы данных.password
— пароль для доступа к базе данных.
-
--mysql-invalidate-query
— запрос для проверки изменений словаря MySQL®. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса. -
--postgresql-source-hosts
— имена хоста-мастера PostgreSQL и его реплик, которые будут использоваться в качестве источника PostgreSQL. Хосты должны находиться в той же сети, что и кластер ClickHouse®. -
--postgresql-invalidate-query
— запрос для проверки изменений словаря PostgreSQL. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса. -
--layout-type
— способ размещения словаря в памяти. Поддерживаются способы:flat
,hashed
,cache
,range_hashed
,complex_key_hashed
,complex_key_cache
. Подробнее о способах размещения словарей в памяти читайте в документации ClickHouse® . -
--layout-size-in-cells
— количество ячеек кэша для способовcache
,complex_key_cache
. Подробнее о кэше читайте в документации ClickHouse® . -
--structure-id
— имя ключевого столбца словаря. Ключевой столбец должен иметь тип данных UInt64. Используется для способовflat
,hashed
,cache
,range_hashed
. Подробнее о ключах читайте в документации ClickHouse® . -
--structure-key
— описание составного ключа словаря. Составной ключ может состоять из одного или более элементов. Используется для способовcomplex_key_hashed
,complex_key_cache
:name
— имя столбца.type
— тип данных столбца.null-value
— значение по умолчанию для пустого элемента. При загрузке словаря все пустые элементы будут заменены на это значение. Нельзя указать значениеNULL
.expression
— выражение , которое ClickHouse® выполняет со значением столбца.hierarchical
— признак поддержки иерархии.injective
— признак инъективности отображенияid
→attribute
.
Подробнее о параметрах составного ключа читайте в документации ClickHouse®
.Важно
Настройки
--structure-id
и--structure-key
— взаимоисключающие. Использование одной делает невозможным использование другой. -
--structure-attribute
— описание полей, доступных для запросов к базе данных:name
— имя столбца.type
— тип данных столбца.null-value
— значение по умолчанию для пустого элемента. При загрузке словаря все пустые элементы будут заменены на это значение. Нельзя указать значениеNULL
.expression
— выражение , которое ClickHouse® выполняет со значением столбца.hierarchical
— признак поддержки иерархии.injective
— признак инъективности отображенияid
→attribute
.
-
--fixed-lifetime
— фиксированный период между обновлениями словаря в секундах. -
--lifetime-range
— диапазон, внутри которого ClickHouse® случайно выберет время для обновления. Это поможет распределить нагрузку на источник словаря при обновлении на большом количестве серверов.min
— минимальное значение периода между обновлениями словаря в секундах.max
— максимальное значение периода между обновлениями словаря в секундах.
Важно
Настройки
--fixed-lifetime
и--lifetime-range
— взаимоисключающие. Использование одной делает невозможным использование другой.
-
externalDictionary
– настройки нового словаря:-
name
— имя нового словаря. -
***Source
– источник данных для словаря. Выберите один из перечисленных источников и укажите его настройки:clickhouseSource
— источник ClickHouse®db
— имя базы данных источника.table
— имя таблицы источника.where
— условие для выбора строк, из которых будет сформирован словарь. Например, условие выбораid=10
эквивалентно SQL-командеWHERE id=10
.host
— имя хоста источника. Хост должен находиться в той же сети, что и кластер ClickHouse®.port
— порт для подключения к источнику.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.
mongodbSource
— источник MongoDBdb
— имя базы данных источника.host
— имя хоста источника. Хост должен находиться в той же сети, что и кластер ClickHouse®.port
— порт для подключения к источнику.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.collection
— имя коллекции источника.
mysqlSource
– источник MySQL®db
— имя базы данных источника.table
— имя таблицы источника.where
— условие для выбора строк, из которых будет сформирован словарь. Например, условие выбораid=10
эквивалентно SQL-командеWHERE id=10
.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.replicas
— настройки реплик источника:host
— имя хоста реплики. Хост должен находиться в той же сети, что и кластер ClickHouse®.priority
— приоритет реплики. При попытке соединения ClickHouse® обходит реплики в соответствии с приоритетом. Чем меньше цифра, тем выше приоритет.port
— порт для подключения к реплике.user
— имя пользователя базы данных.password
— пароль для доступа к базе данных.
invalidateQuery
— запрос для проверки изменений словаря MySQL®. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса.shareConnection
– признак общего подключения к источнику для нескольких запросов.closeConnection
— признак закрытия подключения к источнику после каждого запроса.
postgresqlSource
— источник PostgreSQLdb
— имя базы данных источника.table
— имя таблицы источника.port
— порт для подключения к источнику.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.sslMode
— режим для установки защищенного SSL TCP/IP соединения с базой данных PostgreSQL. Допустимые значения:DISABLE
,ALLOW
,PREFER
,VERIFY_CA
,VERIFY_FULL
.hosts
— имена хоста-мастера PostgreSQL и его реплик, которые будут использоваться в качестве источника словаря. Хосты должны находиться в той же сети, что и кластер ClickHouse®.invalidateQuery
— запрос для проверки изменений словаря. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса.
httpSource
– источник HTTP(s)url
— URL HTTP(s)-источника.format
— формат файла для HTTP(s)-источника. Подробнее о форматах читайте в документации ClickHouse® .headers
– особые HTTP-заголовки запроса к источнику:name
– имя заголовка.value
— значение заголовка.
-
layout.type
— способ размещения словаря в памяти. Поддерживаются способы:FLAT
,HASHED
,CACHE
,RANGE_HASHED
,COMPLEX_KEY_HASHED
,COMPLEX_KEY_CACHE
. Подробнее о способах размещения словарей в памяти читайте в документации ClickHouse® . -
layout.sizeInCells
— количество ячеек кэша для способовCACHE
,COMPLEX_KEY_CACHE
. Подробнее о кэше читайте в документации ClickHouse® . -
layout.maxArraySize
— максимальное значение ключа для способаFLAT
. Подробнее о кэше читайте в документации ClickHouse® . -
structure.id.name
— имя ключевого столбца словаря. Ключевой столбец должен иметь тип данных UInt64. Используется для способовFLAT
,HASHED
,CACHE
,RANGE_HASHED
. Подробнее о ключах читайте в документации ClickHouse® . -
structure.key.attributes
— описание составного ключа словаря. Составной ключ может состоять из одного или более элементов. Используется для способовCOMPLEX_KEY_HASHED
,COMPLEX_KEY_CACHE
:name
— имя столбца.type
— тип данных столбца.nullValue
— значение по умолчанию для пустого элемента. При загрузке словаря все пустые элементы будут заменены на это значение. Нельзя указать значениеNULL
.expression
— выражение , которое ClickHouse® выполняет со значением столбца.hierarchical
— признак поддержки иерархии.injective
— признак инъективности отображенияid
→attribute
.
Подробнее о параметрах составного ключа читайте в документации ClickHouse®
.Важно
Поля
structure.id.name
иstructure.key.attributes
— взаимоисключающие. Использование одного делает невозможным использование другого. -
structure.attributes
— описание полей, доступных для запросов к базе данных:name
— имя столбца.type
— тип данных столбца.nullValue
— значение по умолчанию для пустого элемента. При загрузке словаря все пустые элементы будут заменены на это значение. Нельзя указать значениеNULL
.expression
— выражение , которое ClickHouse® выполняет со значением столбца.hierarchical
— признак поддержки иерархии.injective
— признак инъективности отображенияid
→attribute
.
-
fixedLifetime
— фиксированный период между обновлениями словаря в секундах. -
lifetimeRange
— диапазон, внутри которого ClickHouse® случайно выберет время для обновления. Это поможет распределить нагрузку на источник словаря при обновлении на большом количестве серверов. Границы диапазона задаются в настройках:min
— минимальное значение периода между обновлениями словаря в секундах.max
— максимальное значение периода между обновлениями словаря в секундах.
Важно
Поля
fixedLifetime
иlifetimeRange
— взаимоисключающие. Использование одного делает невозможным использование другого.
-
-
external_dictionary
– настройки нового словаря:-
name
— имя нового словаря. -
***_source
– источник данных для словаря. Выберите один из перечисленных источников и укажите его настройки:clickhouse_source
— источник ClickHouse®db
— имя базы данных источника.table
— имя таблицы источника.where
— условие для выбора строк, из которых будет сформирован словарь. Например, условие выбораid=10
эквивалентно SQL-командеWHERE id=10
.host
— имя хоста источника. Хост должен находиться в той же сети, что и кластер ClickHouse®.port
— порт для подключения к источнику.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.
mongodb_source
— источник MongoDBdb
— имя базы данных источника.host
— имя хоста источника. Хост должен находиться в той же сети, что и кластер ClickHouse®.port
— порт для подключения к источнику.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.collection
— имя коллекции источника.
mysql_source
– источник MySQL®db
— имя базы данных источника.table
— имя таблицы источника.where
— условие для выбора строк, из которых будет сформирован словарь. Например, условие выбораid=10
эквивалентно SQL-командеWHERE id=10
.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.replicas
— настройки реплик источника:host
— имя хоста реплики. Хост должен находиться в той же сети, что и кластер ClickHouse®.priority
— приоритет реплики. При попытке соединения ClickHouse® обходит реплики в соответствии с приоритетом. Чем меньше цифра, тем выше приоритет.port
— порт для подключения к реплике.user
— имя пользователя базы данных.password
— пароль для доступа к базе данных.
invalidate_query
— запрос для проверки изменений словаря MySQL®. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса.share_connection
– признак общего подключения к источнику для нескольких запросов.close_connection
— признак закрытия подключения к источнику после каждого запроса.
postgresql_source
— источник PostgreSQLdb
— имя базы данных источника.table
— имя таблицы источника.port
— порт для подключения к источнику.user
— имя пользователя базы данных источника.password
— пароль для доступа к базе данных источника.ssl_mode
— режим для установки защищенного SSL TCP/IP соединения с базой данных PostgreSQL. Допустимые значения:DISABLE
,ALLOW
,PREFER
,VERIFY_CA
,VERIFY_FULL
.hosts
— имена хоста-мастера PostgreSQL и его реплик, которые будут использоваться в качестве источника словаря. Хосты должны находиться в той же сети, что и кластер ClickHouse®.invalidate_query
— запрос для проверки изменений словаря. ClickHouse® будет обновлять словарь только при изменении результата выполнения этого запроса.
http_source
– источник HTTP(s)url
— URL HTTP(s)-источника.format
— формат файла для HTTP(s)-источника. Подробнее о форматах читайте в документации ClickHouse® .headers
– особые HTTP-заголовки запроса к источнику:name
– имя заголовка.value
— значение заголовка.
-
layout.type
— способ размещения словаря в памяти. Поддерживаются способы:FLAT
,HASHED
,CACHE
,RANGE_HASHED
,COMPLEX_KEY_HASHED
,COMPLEX_KEY_CACHE
. Подробнее о способах размещения словарей в памяти читайте в документации ClickHouse® . -
layout.size_in_cells
— количество ячеек кэша для способовCACHE
,COMPLEX_KEY_CACHE
. Подробнее о кэше читайте в документации ClickHouse® . -
layout.max_array_size
— максимальное значение ключа для способаFLAT
. Подробнее о кэше читайте в документации ClickHouse® . -
structure.id.name
— имя ключевого столбца словаря. Ключевой столбец должен иметь тип данных UInt64. Используется для способовFLAT
,HASHED
,CACHE
,RANGE_HASHED
. Подробнее о ключах читайте в документации ClickHouse® . -
structure.key.attributes
— описание составного ключа словаря. Составной ключ может состоять из одного или более элементов. Используется для способовCOMPLEX_KEY_HASHED
,COMPLEX_KEY_CACHE
:name
— имя столбца.type
— тип данных столбца.null_value
— значение по умолчанию для пустого элемента. При загрузке словаря все пустые элементы будут заменены на это значение. Нельзя указать значениеNULL
.expression
— выражение , которое ClickHouse® выполняет со значением столбца.hierarchical
— признак поддержки иерархии.injective
— признак инъективности отображенияid
→attribute
.
Подробнее о параметрах составного ключа читайте в документации ClickHouse®
.Важно
Поля
structure.id.name
иstructure.key.attributes
— взаимоисключающие. Использование одного делает невозможным использование другого. -
structure.attributes
— описание полей, доступных для запросов к базе данных:name
— имя столбца.type
— тип данных столбца.null_value
— значение по умолчанию для пустого элемента. При загрузке словаря все пустые элементы будут заменены на это значение. Нельзя указать значениеNULL
.expression
— выражение , которое ClickHouse® выполняет со значением столбца.hierarchical
— признак поддержки иерархии.injective
— признак инъективности отображенияid
→attribute
.
-
fixed_lifetime
— фиксированный период между обновлениями словаря в секундах. -
lifetime_range
— диапазон, внутри которого ClickHouse® случайно выберет время для обновления. Это поможет распределить нагрузку на источник словаря при обновлении на большом количестве серверов. Границы диапазона задаются в настройках:min
— минимальное значение периода между обновлениями словаря в секундах.max
— максимальное значение периода между обновлениями словаря в секундах.
Важно
Поля
fixed_lifetime
иlifetime_range
— взаимоисключающие. Использование одного делает невозможным использование другого.
-
Примеры
Пусть существует кластер ClickHouse® mych
с идентификатором cat0adul1fj0********
, и в этот кластер нужно подключить словарь с тестовыми характеристиками:
- имя словаря
mychdict
; - имя ключевого столбца
id
; - поля, доступные для запросов к базе данных:
id
с типомUInt64
;field1
с типомString
;
- фиксированный период между обновлениями словаря 300 секунд;
- способ размещения словаря в памяти
cache
с размером кеша в 1024 ячейки; - источник PostgreSQL:
- база данных
db1
; - имя таблицы
table1
; - порт для подключения
6432
; - имя пользователя базы данных
user1
; - пароль для доступа к базе данных
user1user1
; - режим для установки защищенного SSL TCP/IP соединения с базой данных
verify-full
; - особый FQDN хоста-мастера
c-c9qash3nb1v9********.rw.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 \
--layout-size-in-cells 1024 \
--postgresql-source db=db1,`
`table=table1,`
`port=6432,`
`user=user1,`
`password=user1user1,`
`ssl-mode=verify-full \
--postgresql-source-hosts=c-c9qash3nb1v9********.rw.mdb.yandexcloud.net
-
Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
export IAM_TOKEN="<IAM-токен>"
-
Создайте файл
body.json
и добавьте в него следующее содержимое:{ "externalDictionary": { "name": "mychdict", "structure": { "id": { "name": "id" }, "attributes": [ { "name": "id", "type": "UInt64" }, { "name": "field1", "type": "String" } ] }, "layout": { "type": "CACHE", "sizeInCells": "1024" }, "fixedLifetime": "300", "postgresqlSource": { "db": "db1", "table": "table", "port": "5432", "user": "user1", "password": "user1user1", "sslMode": "VERIFY_FULL", "hosts": ["c-c9qash3nb1v9********.rw.mdb.yandexcloud.net"] } } }
-
Выполните запрос c помощью cURL
:curl \ --request POST \ --header "Authorization: Bearer $IAM_TOKEN" \ --header "Content-Type: application/json" \ --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/cat0adul1fj0********:createExternalDictionary' \ --data '@body.json'
-
Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
export IAM_TOKEN="<IAM-токен>"
-
Клонируйте репозиторий cloudapi
:cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
Далее предполагается, что содержимое репозитория находится в директории
~/cloudapi/
. -
Создайте файл
body.json
и добавьте в него следующее содержимое:{ "cluster_id": "cat0adul1fj0********", "external_dictionary": { "name": "mychdict", "structure": { "id": { "name": "id" }, "attributes": [ { "name": "id", "type": "UInt64" }, { "name": "field1", "type": "String" } ] }, "layout": { "type": "CACHE", "size_in_cells": "1024" }, "fixed_lifetime": "300", "postgresql_source": { "db": "db1", "table": "table", "port": "5432", "user": "user1", "password": "user1user1", "ssl_mode": "VERIFY_FULL", "hosts": ["c-c9qash3nb1v9********.rw.mdb.yandexcloud.net"] } } }
-
Выполните запрос с помощью gRPCurl
:grpcurl \ -format json \ -import-path ~/cloudapi/ \ -import-path ~/cloudapi/third_party/googleapis/ \ -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/cluster_service.proto \ -rpc-header "Authorization: Bearer $IAM_TOKEN" \ -d @ \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.clickhouse.v1.ClusterService.CreateExternalDictionary \ < body.json
ClickHouse® является зарегистрированным товарным знаком ClickHouse, Inc