Управление собственной геобазой в Managed Service for ClickHouse®

Статья создана

Улучшена

Обновлена 27 ноября 2025 г.

Создать геобазу
Загрузить геобазу в Yandex Object Storage
Подключить геобазу к кластеру ClickHouse®
Отключить геобазу

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

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

Если собственная геобаза не используется, отключите ее.

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

Создайте файл regions_hierarchy.txt с иерархией регионов. Файл должен представлять собой таблицу в формате TSV без заголовков и со столбцами:
- идентификатор региона (UInt32);
- идентификатор родительского региона (UInt32);
- тип региона (UInt8):
  - 1 — континент;
  - 3 — страна;
  - 4 — федеральный округ;
  - 5 — область;
  - 6 — город;
- население (UInt32) — необязательный столбец.
Чтобы добавить альтернативную иерархию регионов, создайте файлы regions_hierarchy_<суффикс>.txt с аналогичной структурой. Чтобы затем воспользоваться альтернативной геобазой, передайте этот суффикс при вызове функции. Например:
- regionToCountry(RegionID) — использует словарь по умолчанию: regions_hierarchy.txt;
- regionToCountry(RegionID, 'alt') — использует словарь с суффиксом alt: regions_hierarchy_alt.txt.
Создайте файл regions_names.txt с именами регионов. Файл должен представлять собой таблицу в формате TSV без заголовков и со столбцами:
- идентификатор региона (UInt32);
- имя региона (String) — не может содержать символы табуляции или переводы строк, даже экранированные.
Чтобы добавить в базу имена регионов на других языках, создайте файлы regions_names_<код_языка>.txt с аналогичной структурой. Например, regions_names_en.txt для английского языка и regions_names_tr.txt для турецкого.
Создайте из файлов геобазы архив в формате tar, tar.gz или zip.

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

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

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

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

Консоль управления

CLI

Terraform

REST API

gRPC API

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

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

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

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

Посмотрите описание команды CLI для изменения конфигурации кластера:
```
yc managed-clickhouse cluster update-config --help
```
Выполните команду, передав ссылку на архив с подключаемой геобазой в параметре geobase_uri:
```
yc managed-clickhouse cluster update-config <имя_или_идентификатор_кластера> \
     --set geobase_uri="<ссылка_на_архив_с_геобазой_в_Object_Storage>"
```
Идентификатор и имя кластера можно запросить со списком кластеров в каталоге.

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

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

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

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

Проверьте корректность настроек.
1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.
2. Выполните команду:
```
terraform validate
```
  Если в файлах конфигурации есть ошибки, Terraform на них укажет.
Подтвердите изменение ресурсов.
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 минут
  }
}

Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
```
export IAM_TOKEN="<IAM-токен>"
```
Воспользуйтесь методом Cluster.Update и выполните запрос, например, с помощью cURL:

Важно

Метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре updateMask (одной строкой через запятую).
```
curl \
    --request PATCH \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --header "Content-Type: application/json" \
    --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<идентификатор_кластера>' \
    --data '{
              "updateMask": "configSpec.clickhouse.config.geobaseUri",
              "configSpec": {
                "clickhouse": {
                  "config": {
                    "geobaseUri": "<ссылка>"
                  }
                }
              }
            }'
```
Где:
- updateMask — перечень изменяемых параметров в одну строку через запятую.
  
  В данном случае указан только один параметр: configSpec.clickhouse.config.geobaseUri.
- configSpec.clickhouse.config.geobaseUri — ссылка на архив с геобазой в Object Storage.
Идентификатор кластера можно запросить со списком кластеров в каталоге.
Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
```
export IAM_TOKEN="<IAM-токен>"
```
Клонируйте репозиторий cloudapi:
```
cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
```
Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.
Воспользуйтесь вызовом ClusterService.Update и выполните запрос, например, с помощью gRPCurl:
Важно
Метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре update_mask (в виде массива строк paths[]).
Формат перечисления настроек
"update_mask": { "paths": [ "<настройка_1>", "<настройка_2>", ... "<настройка_N>" ] }
```
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": "<идентификатор_кластера>",
          "update_mask": {
            "paths": [
              "config_spec.clickhouse.config.geobase_uri"
            ]
          },
          "config_spec": {
            "clickhouse": {
              "config": {
                "geobase_uri": "<ссылка>"
              }
            }
          }
        }' \
    mdb.api.cloud.yandex.net:443 \
    yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
```
Где:
- update_mask — перечень изменяемых параметров в виде массива строк paths[].
  
  В данном случае указан только один параметр: config_spec.clickhouse.config.geobase_uri.
- config_spec.clickhouse.config.geobase_uri — ссылка на архив с геобазой в Object Storage.
Идентификатор кластера можно запросить со списком кластеров в каталоге.
Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Отключить геобазу

Консоль управления

CLI

REST API

gRPC API

В консоли управления выберите каталог, в котором находится кластер.
Перейдите в сервис Managed Service for ClickHouse.
Выберите кластер и нажмите кнопку Редактировать на панели сверху.
В блоке Настройки СУБД нажмите кнопку Настроить.
В поле Geobase uri удалите значение.

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

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

Посмотрите описание команды CLI для изменения конфигурации кластера:
```
yc managed-clickhouse cluster update-config --help
```
Выполните команду, передав пустое значение параметра geobase_uri:
```
yc managed-clickhouse cluster update-config <имя_или_идентификатор_кластера> \
     --set geobase_uri=""
```
Идентификатор и имя кластера можно запросить со списком кластеров в каталоге.

Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
```
export IAM_TOKEN="<IAM-токен>"
```
Воспользуйтесь методом Cluster.Update и выполните запрос, например, с помощью cURL:

Важно

Метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре updateMask (одной строкой через запятую).
```
curl \
    --request PATCH \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --header "Content-Type: application/json" \
    --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<идентификатор_кластера>' \
    --data '{
              "updateMask": "configSpec.clickhouse.config.geobaseUri",
              "configSpec": {
                "clickhouse": {
                  "config": {
                    "geobaseUri": ""
                  }
                }
              }
            }'
```
Где:
- updateMask — перечень изменяемых параметров в одну строку через запятую.
  
  В данном случае указан только один параметр: configSpec.clickhouse.config.geobaseUri.
- configSpec.clickhouse.config.geobaseUri — ссылка на архив с геобазой в Object Storage. Укажите пустое значение в этом параметре.
Идентификатор кластера можно запросить со списком кластеров в каталоге.
Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
```
export IAM_TOKEN="<IAM-токен>"
```
Клонируйте репозиторий cloudapi:
```
cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
```
Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.
Воспользуйтесь вызовом ClusterService.Update и выполните запрос, например, с помощью gRPCurl:
Важно
Метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре update_mask (в виде массива строк paths[]).
Формат перечисления настроек
"update_mask": { "paths": [ "<настройка_1>", "<настройка_2>", ... "<настройка_N>" ] }
```
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": "<идентификатор_кластера>",
          "update_mask": {
            "paths": [
              "config_spec.clickhouse.config.geobase_uri"
            ]
          },
          "config_spec": {
            "clickhouse": {
              "config": {
                "geobase_uri": ""
              }
            }
          }
        }' \
    mdb.api.cloud.yandex.net:443 \
    yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
```
Где:
- update_mask — перечень изменяемых параметров в виде массива строк paths[].
  
  В данном случае указан только один параметр: config_spec.clickhouse.config.geobase_uri.
- config_spec.clickhouse.config.geobase_uri — ссылка на архив с геобазой в Object Storage. Укажите пустое значение в этом параметре.
Идентификатор кластера можно запросить со списком кластеров в каталоге.
Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

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

Управление собственной геобазой в Managed Service for ClickHouse®

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

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

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

Отключить геобазуОтключить геобазу

Была ли статья полезна?

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

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

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

Отключить геобазу