Подключение внешних словарей в Managed Service for ClickHouse®

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

Чтобы получить список внешних словарей в кластере ClickHouse®:

1. Посмотрите описание команды CLI для получения детальной информации о кластере:

   yc managed-clickhouse cluster get --help
   

2. Выполните команду:

   yc managed-clickhouse cluster get <имя_кластера>
   

Подключенные словари отображаются в блоке dictionaries: результата выполнения команды.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Воспользуйтесь методом Cluster.ListExternalDictionaries и выполните запрос, например, с помощью cURL:

   curl \
       --request GET \
       --header "Authorization: Bearer $IAM_TOKEN" \
       --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<идентификатор_кластера>/externalDictionaries'
   

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Воспользуйтесь вызовом 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
   

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Подключитесь к нужной базе данных кластера Managed Service for ClickHouse® с помощью clickhouse-client.
2. Выполните запрос SHOW DICTIONARIES.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

Чтобы создать внешний словарь в кластере ClickHouse®:

1. Посмотрите описание команды CLI для добавления словарей:

   yc managed-clickhouse cluster add-external-dictionary --help
   

2. Выполните команду добавления словаря и укажите его настройки:

   yc managed-clickhouse cluster add-external-dictionary \
      --name=<имя_кластера_ClickHouse®> \
      --dict-name=<имя_словаря> \
      ...
   

Чтобы создать внешний словарь в кластере ClickHouse®:

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Воспользуйтесь методом Cluster.CreateExternalDictionary и выполните запрос, например, с помощью cURL:

   1. Создайте файл 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.

      Подробное описание атрибутов и других настроек словаря приведено ниже.

   2. Выполните запрос:

      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'
      

      Идентификатор кластера можно запросить со списком кластеров в каталоге.

3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Чтобы создать внешний словарь в кластере ClickHouse®:

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Воспользуйтесь вызовом ClusterService.CreateExternalDictionary и выполните запрос, например, с помощью gRPCurl:

   1. Создайте файл 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.

      Подробное описание атрибутов и других настроек словаря приведено ниже.

      Идентификатор кластера можно запросить со списком кластеров в каталоге.

   2. Выполните запрос:

      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
      

4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Подключитесь к нужной базе данных кластера Managed Service for ClickHouse® с помощью clickhouse-client.

2. Выполните 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®.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Воспользуйтесь методом Cluster.UpdateExternalDictionary и выполните запрос, например, с помощью cURL:

   1. Создайте файл 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.

      Подробное описание атрибутов и других настроек словаря приведено ниже.

   2. Выполните запрос:

      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'
      

      Идентификатор кластера можно запросить со списком кластеров в каталоге.

3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Воспользуйтесь вызовом ClusterService.UpdateExternalDictionary и выполните запрос, например, с помощью gRPCurl:

   1. Создайте файл 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.

      Подробное описание атрибутов и других настроек словаря приведено ниже.

      Идентификатор кластера можно запросить со списком кластеров в каталоге.

   2. Выполните запрос:

      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
      

4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

Чтобы удалить внешний словарь:

1. Посмотрите описание команды CLI для удаления словаря:

   yc managed-clickhouse cluster remove-external-dictionary --help
   

2. Удалите словарь с помощью команды:

   yc managed-clickhouse cluster remove-external-dictionary \
      --name=<имя_кластера> \
      --dict-name=<имя_словаря>
   

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Воспользуйтесь методом 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 — имя словаря, который нужно удалить. Имя словаря можно запросить со списком внешних словарей в кластере.

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

3. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Воспользуйтесь вызовом 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 — имя словаря, который нужно удалить. Имя словаря можно запросить со списком внешних словарей в кластере.

   Идентификатор кластера можно запросить со списком кластеров в каталоге.

4. Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

1. Подключитесь к нужной базе данных кластера Managed Service for ClickHouse® с помощью clickhouse-client.
2. Выполните запрос DROP DICTIONARY <имя_БД>.<имя_словаря>.

• --dict-name — имя нового словаря.

• --***-source — настройки источника словаря. Выберите один из перечисленных источников и укажите его настройки:

  --clickhouse-source — источник ClickHouse®

  • host — имя хоста источника. Необязательный параметр.

    Хост должен находиться в той же сети, что и кластер ClickHouse®.

  • port — порт для подключения к источнику. Необязательный параметр.

  • db — имя базы данных источника.

  • user — имя пользователя базы данных источника.

  • password — пароль для доступа к базе данных источника.

  • table — имя таблицы источника.

  • where — условие для выбора строк, из которых будет сформирован словарь. Например, условие выбора id=10 эквивалентно SQL-команде WHERE id=10.

  • secure — использовать ли SSL для установки соединения.

  --mongodb-source — источник MongoDB

  • host — имя хоста источника. Хост должен находиться в той же сети, что и кластер ClickHouse®.
  • port — порт для подключения к источнику.
  • db — имя базы данных источника.
  • user — имя пользователя базы данных источника.
  • password — пароль для доступа к базе данных источника.
  • connection — имя коллекции источника.
  --mysql-source – источник MySQL®

  • db — имя базы данных источника.
  • user — имя пользователя базы данных источника.
  • password — пароль для доступа к базе данных источника.
  • table — имя таблицы источника.
  • where — условие для выбора строк, из которых будет сформирован словарь. Например, условие выбораid=10 эквивалентно SQL-команде WHERE id=10.
  • share-connection – сделать ли соединение общим для нескольких запросов.
  • close-connection — закрывать ли соединение после каждого запроса.
  --postgresql-source — источник PostgreSQL

  • table — имя таблицы источника.
  • 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®.

• --http-header — особый HTTP-заголовок запроса к источнику HTTP(s):

  • name – имя заголовка;
  • value — значение заголовка.

• --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, complex_key_hashed, range_hashed, cache, complex_key_cache, sparse_hashed, complex_key_sparse_hashed, complex_key_range_hashed, direct, complex_key_direct, ip_trie. Подробнее о способах размещения словарей в памяти читайте в документации ClickHouse®.

• --layout-size-in-cells — количество ячеек кэша для способов cache, complex_key_cache. Подробнее о кэше читайте в документации ClickHouse®.

• --layout-allow-read-expired-keys — определяет, разрешать ли считывать ключи с истекшим сроком действия. Используется для способов cache и complex_key_cache. Подробнее читайте в документации ClickHouse®.

• Настройки очереди обновлений, в которой создаются задачи обновления кэша, если ключи не найдены в словаре. Настройки используются для способов cache и complex_key_cache.

  • --layout-max-update-queue-size — максимальное количество задач обновления в очереди. Значение по умолчанию — 100000.
  • --layout-update-queue-push-timeout-milliseconds — максимальное время ожидания в миллисекундах для отправки задачи обновления в очередь. Значение по умолчанию — 10.
  • --layout-query-wait-timeout-milliseconds — максимальное время ожидания в миллисекундах для завершения задачи обновления. Значение по умолчанию — 60000 (1 минута).
  • --layout-max-threads-for-updates — максимальное количество потоков для обновления словаря кэша. Значение по умолчанию — 4.

  Подробнее читайте в документации ClickHouse®.

• Настройки размера плоских массивов. Используются для способа flat.

  • --layout-initial-array-size — начальный размер ключа словаря. Значение по умолчанию — 1024.
  • --layout-max-array-size — максимальный размер ключа словаря. Определяет размер памяти, который использует словарь, так как этот размер пропорционален значению самого большого ключа. Значение по умолчанию — 500000.

  Подробнее читайте в документации ClickHouse®.

• --layout-access-to-key-from-attributes — позволяет получать имя составного ключа с помощью функции dictGetString. Используется для способа ip_trie. Включение этой настройки увеличивает нагрузку на оперативную память.

• --structure-id — имя ключевого столбца словаря. Ключевой столбец должен иметь тип данных UInt64. Используется для способов flat, hashed, range_hashed, cache, sparse_hashed, direct. Подробнее о ключах читайте в документации ClickHouse®.

• --structure-key — описание составного ключа словаря. Составной ключ может состоять из одного или более элементов. Используется для способов complex_key_* и ip_trie:

  • 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 — пароль для доступа к базе данных источника.

    • secure — использовать ли SSL для установки соединения.

    mongodbSource — источник MongoDB

    • db — имя базы данных источника.
    • 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 — источник PostgreSQL

    • db — имя базы данных источника.
    • 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, COMPLEX_KEY_HASHED, RANGE_HASHED, CACHE, COMPLEX_KEY_CACHE, SPARSE_HASHED, COMPLEX_KEY_SPARSE_HASHED, COMPLEX_KEY_RANGE_HASHED, DIRECT, COMPLEX_KEY_DIRECT, IP_TRIE. Подробнее о способах размещения словарей в памяти читайте в документации ClickHouse®.

  • layout.sizeInCells — количество ячеек кэша для способов CACHE, COMPLEX_KEY_CACHE. Подробнее о кэше читайте в документации ClickHouse®.

  • layout.allowReadExpiredKeys — определяет, разрешать ли считывать ключи с истекшим сроком действия. Используется для способов CACHE и COMPLEX_KEY_CACHE. Подробнее читайте в документации ClickHouse®.

  • Настройки очереди обновлений, в которой создаются задачи обновления кэша, если ключи не найдены в словаре. Настройки используются для способов CACHE и COMPLEX_KEY_CACHE.

    • layout.maxUpdateQueueSize — максимальное количество задач обновления в очереди. Значение по умолчанию — 100000.
    • layout.updateQueuePushTimeoutMilliseconds — максимальное время ожидания в миллисекундах для отправки задачи обновления в очередь. Значение по умолчанию — 10.
    • layout.queryWaitTimeoutMilliseconds — максимальное время ожидания в миллисекундах для завершения задачи обновления. Значение по умолчанию — 60000 (1 минута).
    • layout.maxThreadsForUpdates — максимальное количество потоков для обновления словаря кэша. Значение по умолчанию — 4.

    Подробнее читайте в документации ClickHouse®.

  • Настройки размера плоских массивов. Используются для способа FLAT.

    • layout.initialArraySize — начальный размер ключа словаря. Значение по умолчанию — 1024.
    • layout.maxArraySize — максимальный размер ключа словаря. Определяет размер памяти, который использует словарь, так как этот размер пропорционален значению самого большого ключа. Значение по умолчанию — 500000.

    Подробнее читайте в документации ClickHouse®.

  • layout.accessToKeyFromAttributes — позволяет получать имя составного ключа с помощью функции dictGetString. Используется для способа IP_TRIE. Включение этой настройки увеличивает нагрузку на оперативную память.

  • structure.id.name — имя ключевого столбца словаря. Ключевой столбец должен иметь тип данных UInt64. Используется для способов FLAT, HASHED, RANGE_HASHED, CACHE, SPARSE_HASHED, DIRECT. Подробнее о ключах читайте в документации ClickHouse®.

  • structure.key.attributes — описание составного ключа словаря. Составной ключ может состоять из одного или более элементов. Используется для способов COMPLEX_KEY_* и IP_TRIE:

    • 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 — пароль для доступа к базе данных источника.

    • secure — использовать ли SSL для установки соединения.

    mongodb_source — источник MongoDB

    • db — имя базы данных источника.
    • 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 — источник PostgreSQL

    • db — имя базы данных источника.
    • 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, COMPLEX_KEY_HASHED, RANGE_HASHED, CACHE, COMPLEX_KEY_CACHE, SPARSE_HASHED, COMPLEX_KEY_SPARSE_HASHED, COMPLEX_KEY_RANGE_HASHED, DIRECT, COMPLEX_KEY_DIRECT, IP_TRIE. Подробнее о способах размещения словарей в памяти читайте в документации ClickHouse®.

  • layout.size_in_cells — количество ячеек кэша для способов CACHE, COMPLEX_KEY_CACHE. Подробнее о кэше читайте в документации ClickHouse®.

  • layout.allow_read_expired_keys — определяет, разрешать ли считывать ключи с истекшим сроком действия. Используется для способов CACHE и COMPLEX_KEY_CACHE. Подробнее читайте в документации ClickHouse®.

  • Настройки очереди обновлений, в которой создаются задачи обновления кэша, если ключи не найдены в словаре. Настройки используются для способов CACHE и COMPLEX_KEY_CACHE.

    • layout.max_update_queue_size — максимальное количество задач обновления в очереди. Значение по умолчанию — 100000.
    • layout.update_queue_push_timeout_milliseconds — максимальное время ожидания в миллисекундах для отправки задачи обновления в очередь. Значение по умолчанию — 10.
    • layout.query_wait_timeout_milliseconds — максимальное время ожидания в миллисекундах для завершения задачи обновления. Значение по умолчанию — 60000 (1 минута).
    • layout.max_threads_for_updates — максимальное количество потоков для обновления словаря кэша. Значение по умолчанию — 4.

    Подробнее читайте в документации ClickHouse®.

  • Настройки размера плоских массивов. Используются для способа FLAT.

    • layout.initial_array_size — начальный размер ключа словаря. Значение по умолчанию — 1024.
    • layout.max_array_size — максимальный размер ключа словаря. Определяет размер памяти, который использует словарь, так как этот размер пропорционален значению самого большого ключа. Значение по умолчанию — 500000.

    Подробнее читайте в документации ClickHouse®.

  • layout.access_to_key_from_attributes — позволяет получать имя составного ключа с помощью функции dictGetString. Используется для способа IP_TRIE. Включение этой настройки увеличивает нагрузку на оперативную память.

  • structure.id.name — имя ключевого столбца словаря. Ключевой столбец должен иметь тип данных UInt64. Используется для способов FLAT, HASHED, RANGE_HASHED, CACHE, SPARSE_HASHED, DIRECT. Подробнее о ключах читайте в документации ClickHouse®.

  • structure.key.attributes — описание составного ключа словаря. Составной ключ может состоять из одного или более элементов. Используется для способов COMPLEX_KEY_* и IP_TRIE:

    • 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 — взаимоисключающие. Использование одного делает невозможным использование другого.

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Создайте файл 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"]
       }
     }
   }
   

3. Выполните запрос 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'
   

1. Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

   export IAM_TOKEN="<IAM-токен>"
   

2. Клонируйте репозиторий cloudapi:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

3. Создайте файл 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"]
       }
     }
   }
   

4. Выполните запрос с помощью 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