Связаться с намиПодключиться

Подключение собственной геобазы в Managed Service for ClickHouse®

Статья создана
Обновлена 17 октября 2024 г.

Геобаза в ClickHouse® — это текстовые файлы, которые содержат иерархию и имена регионов. Вы можете добавить в ClickHouse® несколько альтернативных геобаз для поддержки разных точек зрения о принадлежности регионов странам. Подробнее читайте в документации ClickHouse®.

Чтобы подключить к кластеру ClickHouse® собственную геобазу:

  1. Создайте ее.
  2. Загрузите геобазу в Yandex Object Storage.
  3. Подключите геобазу к кластеру ClickHouse®.

Создать геобазу

  1. Создайте файл regions_hierarchy.txt с иерархией регионов. Файл должен представлять собой таблицу в формате TSV без заголовков и со столбцами:

    • идентификатор региона (UInt32);
    • идентификатор родительского региона (UInt32);
    • тип региона (UInt8):
      • 1 — континент;
      • 3 — страна;
      • 4 — федеральный округ;
      • 5 — область;
      • 6 — город;
    • население (UInt32) — необязательный столбец.

  2. Чтобы добавить альтернативную иерархию регионов, создайте файлы regions_hierarchy_<суффикс>.txt с аналогичной структурой. Чтобы затем воспользоваться альтернативной геобазой, передайте этот суффикс при вызове функции. Например:

    • regionToCountry(RegionID) — использует словарь по умолчанию: regions_hierarchy.txt;
    • regionToCountry(RegionID, 'alt') — использует словарь с суффиксом alt: regions_hierarchy_alt.txt.

  3. Создайте файл regions_names.txt с именами регионов. Файл должен представлять собой таблицу в формате TSV без заголовков и со столбцами:

    • идентификатор региона (UInt32);
    • имя региона (String) — не может содержать символы табуляции или переводы строк, даже экранированные.

  4. Чтобы добавить в базу имена регионов на других языках, создайте файлы regions_names_<код_языка>.txt с аналогичной структурой. Например, regions_names_en.txt для английского языка и regions_names_tr.txt для турецкого.

  5. Создайте из файлов геобазы архив в формате tar, tar.gz или zip.

Загрузить геобазу в Yandex Object Storage

Managed Service for ClickHouse® работает только с геобазами, которые загружены в Yandex Object Storage и к которым предоставлен доступ на чтение:

  1. Для привязки сервисного аккаунта к кластеру убедитесь, что вашему аккаунту в Yandex Cloud назначена роль iam.serviceAccounts.user или выше.
  2. Загрузите архив с геобазой в Yandex Object Storage.
  3. Подключите сервисный аккаунт к кластеру. С помощью сервисного аккаунта вы настроите доступ к архиву геобазы.
  4. Назначьте роль storage.viewer сервисному аккаунту.
  5. В ACL бакета добавьте разрешение READ сервисному аккаунту.
  6. Получите ссылку на архив с геобазой.

Подключить геобазу к кластеру ClickHouse®

  1. В консоли управления перейдите на страницу каталога и выберите сервис Managed Service for ClickHouse.
  2. Выберите кластер и нажмите кнопку Редактировать на панели сверху.
  3. В блоке Настройки СУБД нажмите кнопку Настроить.
  4. В поле Geobase uri укажите ссылку на архив с геобазой в Yandex Object Storage.

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

По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name или --folder-id.

Чтобы подключить геобазу:

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

    yc managed-clickhouse cluster update-config --help

  2. Выполните команду, передав ссылку на архив с подключаемой геобазой в параметре geobase_uri:

    yc managed-clickhouse cluster update-config <имя_или_идентификатор_кластера> \
     --set geobase_uri="<ссылка_на_архив_с_геобазой_в_Object_Storage>"

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

  1. Откройте актуальный конфигурационный файл Terraform с планом инфраструктуры.

    О том, как создать такой файл, см. в разделе Создание кластера.

  2. Добавьте в настройки кластера Managed Service for ClickHouse® параметр geobase_uri со ссылкой на архив с подключаемой геобазой в Yandex Object Storage:

    resource "yandex_mdb_clickhouse_cluster" "<имя_кластера>" {
  ...
  clickhouse {
    config {
      geobase_uri = "<ссылка_на_архив_с_геобазой_в_Object_Storage>"
      ...
    }
  ...
  }
...
}

  3. Проверьте корректность настроек.

    1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.

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

      terraform validate

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

  4. Подтвердите изменение ресурсов.

    1. Выполните команду для просмотра планируемых изменений:

      terraform plan

      Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

    2. Если вас устраивают планируемые изменения, внесите их:

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

        terraform apply

      2. Подтвердите изменение ресурсов.

      3. Дождитесь завершения операции.

Подробнее см. в документации провайдера Terraform.

Ограничения по времени

Провайдер Terraform ограничивает время на выполнение операций с кластером Managed Service for ClickHouse®:

  • создание, в т. ч. путем восстановления из резервной копии, — 60 минут;
  • изменение — 90 минут;
  • удаление — 30 минут.

Операции, длящиеся дольше указанного времени, прерываются.

Как изменить эти ограничения?

Добавьте к описанию кластера блок timeouts, например:

resource "yandex_mdb_clickhouse_cluster" "<имя_кластера>" {
  ...
  timeouts {
    create = "1h30m" # Полтора часа
    update = "2h"    # 2 часа
    delete = "30m"   # 30 минут
  }
}

Чтобы подключить геобазу к кластеру ClickHouse®, воспользуйтесь методом REST API update для ресурса Cluster или вызовом gRPC API ClusterService/Update и передайте в запросе ссылку на архив с геобазой в Object Storage в параметре geobaseUri.

Важно

Этот метод API сбросит все настройки кластера, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, обязательно передайте название полей, подлежащих изменению, в параметре updateMask.

ClickHouse® является зарегистрированным товарным знаком ClickHouse, Inc.

Предыдущая
Управление пользователями БД
Следующая
Подключение внешних словарей