[Документация Yandex Cloud](../../index.md) > [Yandex Managed Service for ClickHouse®](../index.md) > [Пошаговые инструкции](index.md) > Шардирование > Управление шардами

# Управление шардами в кластере ClickHouse®

Вы можете включить шардирование для кластера, а также добавлять и настраивать отдельные шарды.

## Включить шардирование {#enable}

Кластеры Managed Service for ClickHouse® создаются с одним шардом. Чтобы начать непосредственно шардирование данных, [добавьте](#add-shard) еще один или несколько шардов и [создайте](../tutorials/sharding.md#example) распределенную таблицу.

## Создать шард {#add-shard}

Количество шардов в кластерах Managed Service for ClickHouse® ограничено квотами на количество CPU и объем памяти, которые доступны кластерам БД в вашем облаке. Чтобы проверить используемые ресурсы, откройте страницу [Квоты](https://kz.console.yandex.cloud/cloud?section=quotas) и найдите блок **Managed Service for ClickHouse**.

Вы можете создать сразу несколько шардов в кластере.

{% list tabs group=instructions %}

- Консоль управления {#console}

  1. В [консоли управления](https://kz.console.yandex.cloud) выберите каталог, в котором находится кластер.
  1. Перейдите в сервис **Managed Service for ClickHouse**.
  1. Нажмите на имя нужного кластера и перейдите на вкладку **Шарды**.
  1. Нажмите кнопку **Создать шарды**.
  1. Нажмите на значок ![pencil](../../_assets/console-icons/pencil.svg) в строке нового шарда, чтобы изменить его параметры:
      * имя и вес;
      * конфигурацию хостов шарда.
  1. (Опционально) Нажмите кнопку **Добавить шард**, чтобы добавить дополнительные шарды, и укажите их параметры.
  1. (Опционально) Нажмите кнопку **Добавить хост**, чтобы добавить дополнительные хосты, и укажите их параметры.
  1. Чтобы скопировать схему со случайной реплики одного из шардов на хосты новых шардов, выберите опцию **Копировать схему данных**.

      {% note warning %}
      
      Используйте копирование схемы данных, только если схема одинакова на всех шардах кластера.
      
      {% endnote %}

  1. Нажмите кнопку **Создать шард**.

- CLI {#cli}

  Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), [установите и инициализируйте его](../../cli/quickstart.md#install).

  По умолчанию используется каталог, указанный при [создании](../../cli/operations/profile/profile-create.md) профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду `yc config set folder-id <идентификатор_каталога>`. Также для любой команды вы можете указать другой каталог с помощью параметров `--folder-name` или `--folder-id`. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

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

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

      ```bash
      yc managed-clickhouse shards add --help
      ```

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

      Укажите в команде один или несколько параметров `--shard`: по одному параметру на каждый шард, который нужно создать.

      Пример команды для создания одного шарда (приведены не все доступные параметры):

      ```bash
      yc managed-clickhouse shards add \
        --cluster-name=<имя_кластера> \
        --shard name=<имя_нового_шарда>,`
               `weight=<вес_шарда> \
        --host zone-id=<зона_доступности>,`
              `subnet-name=<имя_подсети>,`
              `shard-name=<имя_шарда> \
        --copy-schema
      ```

      Где:

      * `--cluster-name` — имя кластера.

          Имя кластера можно запросить со [списком кластеров в каталоге](cluster-list.md#list-clusters).

      * `--shard` — параметры шарда:

          * `name` — имя шарда. Должно быть уникальным в кластере.

              Может содержать латинские буквы, цифры, дефис и подчеркивание. Максимальная длина — 63 символа.

          * `weight` — вес шарда.

      * `--host` — параметры хоста, который будет добавлен в шард:

          
          * `zone-id` — [зона доступности](../../overview/concepts/geo-scope.md).
          * `subnet-name` — [имя подсети](../../vpc/concepts/network.md#subnet).


          * `shard-name` — имя шарда, в который будет добавлен хост.

      * `--copy-schema` — опциональный параметр, который инициирует копирование схемы данных со случайной реплики одного из шардов на хосты нового шарда.

          {% note warning %}
          
          Используйте копирование схемы данных, только если схема одинакова на всех шардах кластера.
          
          {% endnote %}


- Terraform {#tf}

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

     О том, как создать такой файл, в разделе [Создание кластера](cluster-create.md).

  1. В описании кластера Managed Service for ClickHouse® добавьте в блок `shards` новый шард, а в блок `hosts` — хост ClickHouse® на этом шарде:

     ```hcl
     resource "yandex_mdb_clickhouse_cluster_v2" "<имя_кластера>" {
       ...
       shards = {
         ...
         "<имя_шарда>" = {
           weight = <вес_шарда>
         }
       }

       hosts = {
         ...
         <имя_хоста> = {
           type       = "CLICKHOUSE"
           zone       = "<зона_доступности>"
           subnet_id  = yandex_vpc_subnet.<подсеть_в_зоне_доступности>.id
           shard_name = "<имя_шарда>"
         }
       }
     }
     ```

  1. (Опционально) Чтобы скопировать схему со случайной реплики одного из шардов на хосты новых шардов, добавьте к описанию кластера поле `copy_schema_on_new_hosts` со значением `true`.

     {% note warning %}
     
     Используйте копирование схемы данных, только если схема одинакова на всех шардах кластера.
     
     {% endnote %}

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

     1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.
     1. Выполните команду:
     
        ```bash
        terraform validate
        ```
     
        Если в файлах конфигурации есть ошибки, Terraform на них укажет.

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

     1. Выполните команду для просмотра планируемых изменений:
     
        ```bash
        terraform plan
        ```
     
        Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.
     
     1. Если вас устраивают планируемые изменения, внесите их:
        1. Выполните команду:
     
           ```bash
           terraform apply
           ```
     
        1. Подтвердите изменение ресурсов.
        1. Дождитесь завершения операции.

  Подробнее в [документации провайдера Terraform](../../terraform/resources/mdb_clickhouse_cluster.md).

  {% note warning "Ограничения по времени" %}
  
  Провайдер Terraform ограничивает время на выполнение операций с кластером Managed Service for ClickHouse®:
  
  * создание, в т. ч. путем восстановления из резервной копии, — 60 минут;
  * изменение — 90 минут;
  * удаление — 30 минут.
  
  Операции, длящиеся дольше указанного времени, прерываются.
  
  {% cut "Как изменить эти ограничения?" %}
  
  Добавьте к описанию кластера блок `timeouts`, например:
  
  ```hcl
  resource "yandex_mdb_clickhouse_cluster_v2" "<имя_кластера>" {
    ...
    timeouts = {
      create = "1h30m" # Полтора часа
      update = "2h"    # 2 часа
      delete = "30m"   # 30 минут
    }
  }
  ```
  
  {% endcut %}
  
  {% endnote %}


- REST API {#api}

  1. [Получите IAM-токен для аутентификации в API](../api-ref/authentication.md) и поместите токен в переменную среды окружения:

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

  1. Воспользуйтесь методом [Cluster.AddShards](../api-ref/Cluster/addShards.md) и выполните запрос, например с помощью [cURL](https://curl.se/):

     1. Создайте файл `body.json` и добавьте в него следующее содержимое:

        ```json
        {
          "shardSpecs": [
            {
              "name": "<имя_шарда>",
              "configSpec": {
                "clickhouse": {
                  "resources": {
                    "resourcePresetId": "<класс_хостов>",
                    "diskSize": "<размер_хранилища_в_байтах>",
                    "diskTypeId": "<тип_диска>"
                  },
                  "weight": "<вес_шарда>"
                }
              }
            }
          ],
          "hostSpecs": [
            {
              "zoneId": "<зона_доступности>",
              "type": "CLICKHOUSE",
              "subnetId": "<идентификатор_подсети>",
              "assignPublicIp": <публичный_доступ_к_хосту>,
              "shardName": "<имя_шарда>"
            }
          ],
          "copySchema": <копирование_схемы_данных>
        }
        ```

        Где:

        * `shardSpecs` — настройки шардов, которые будут добавлены в кластер. Настройки представлены в виде массива элементов. Каждый элемент соответствует отдельному шарду и имеет следующую структуру:

          * `name` — имя шарда.
          * `configSpec.clickhouse.resources` — ресурсы хостов, которые добавляются в создаваемый шард:

            * `resourcePresetId` — идентификатор [класса хостов](../concepts/instance-types.md). Список доступных классов хостов с их идентификаторами можно запросить с помощью метода [ResourcePreset.List](../api-ref/ResourcePreset/list.md).
            * `diskSize` — размер диска в байтах.
            * `diskTypeId` — [тип диска](../concepts/storage.md).

        * `configSpec.clickhouse.weight` — вес шарда.

          По умолчанию каждому шарду назначается вес `1`. Если какому-либо шарду назначить вес больше, данные будут распределены между шардами в соответствии с весами.

          При расчете приоритета шарда при распределении данных складываются веса всех шардов, далее вес каждого шарда делится на полученную сумму. Например, если у одного шарда вес `1`, а у другого — `3`, то у первого шарда приоритет `1/4`, а у второго — `3/4`. Чем выше приоритет, тем больше данных окажется на шарде.

          Подробнее в [документации ClickHouse®](https://clickhouse.com/docs/ru/engines/table-engines/special/distributed).

        * `hostSpecs` — настройки хостов, которые будут добавлены в шард. Настройки представлены в виде массива элементов. Каждый элемент соответствует отдельному хосту и имеет следующую структуру:

          * `zoneId` — зона доступности.
          * `type` — тип хоста. В шарды добавляются только хосты `CLICKHOUSE`.
          * `subnetId` — идентификатор подсети.
          * `assignPublicIp` — доступность хоста из интернета по публичному IP-адресу: `true` или `false`.
          * `shardName` — имя шарда.

        * `copySchema` — копирование схемы данных со случайной реплики одного из шардов на хосты нового шарда. Возможные значения: `true` или `false`.

          {% note warning %}
          
          Используйте копирование схемы данных, только если схема одинакова на всех шардах кластера.
          
          {% endnote %}

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

        ```bash
        curl \
          --request POST \
          --header "Authorization: Bearer $IAM_TOKEN" \
          --header "Content-Type: application/json" \
          --url 'https://mdb.api.yandexcloud.kz/managed-clickhouse/v1/clusters/<идентификатор_кластера>/shards:batchCreate' \
          --data '@body.json'
        ```

        Идентификатор кластера можно запросить со [списком кластеров в каталоге](cluster-list.md#list-clusters).

  1. Убедитесь, что запрос был выполнен успешно, изучив [ответ сервера](../api-ref/Cluster/addShards.md#yandex.cloud.operation.Operation).

- gRPC API {#grpc-api}

  1. [Получите IAM-токен для аутентификации в API](../api-ref/authentication.md) и поместите токен в переменную среды окружения:

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

  1. Клонируйте репозиторий [cloudapi](https://github.com/yandex-cloud/cloudapi):
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Далее предполагается, что содержимое репозитория находится в директории `~/cloudapi/`.
  1. Воспользуйтесь вызовом [ClusterService.AddShards](../api-ref/grpc/Cluster/addShards.md) и выполните запрос, например с помощью [gRPCurl](https://github.com/fullstorydev/grpcurl):

     1. Создайте файл `body.json` и добавьте в него следующее содержимое:

        ```json
        {
          "cluster_id": "<идентификатор_кластера>",
          "shard_specs": [
            {
              "name": "<имя_шарда>",
              "config_spec": {
                "clickhouse": {
                  "resources": {
                    "resource_preset_id": "<класс_хостов>",
                    "disk_size": "<размер_хранилища_в_байтах>",
                    "disk_type_id": "<тип_диска>"
                  },
                  "weight": "<вес_шарда>"
                }
              }
            }
          ],
          "host_specs": [
            {
              "zone_id": "<зона_доступности>",
              "type": "CLICKHOUSE",
              "subnet_id": "<идентификатор_подсети>",
              "assign_public_ip": <публичный_доступ_к_хосту>,
              "shard_name": "<имя_шарда>"
            }
          ],
          "copy_schema": <копирование_схемы_данных>
        }
        ```

        Где:

        * `cluster_id` — идентификатор кластера. Его можно запросить со [списком кластеров в каталоге](cluster-list.md#list-clusters).
        * `shard_specs` — настройки шардов, которые будут добавлены в кластер. Настройки представлены в виде массива элементов. Каждый элемент соответствует отдельному шарду и имеет следующую структуру:

          * `name` — имя шарда.
          * `config_spec.clickhouse.resources` — ресурсы хостов, которые добавляются в создаваемый шард:

            * `resource_preset_id` — идентификатор [класса хостов](../concepts/instance-types.md). Список доступных классов хостов с их идентификаторами можно запросить с помощью метода [ResourcePresetService.List](../api-ref/grpc/ResourcePreset/list.md).
            * `disk_size` — размер диска в байтах.
            * `disk_type_id` — [тип диска](../concepts/storage.md).

          * `config_spec.clickhouse.weight` — вес шарда.

            По умолчанию каждому шарду назначается вес `1`. Если какому-либо шарду назначить вес больше, данные будут распределены между шардами в соответствии с весами.

            При расчете приоритета шарда при распределении данных складываются веса всех шардов, далее вес каждого шарда делится на полученную сумму. Например, если у одного шарда вес `1`, а у другого — `3`, то у первого шарда приоритет `1/4`, а у второго — `3/4`. Чем выше приоритет, тем больше данных окажется на шарде.

            Подробнее в [документации ClickHouse®](https://clickhouse.com/docs/ru/engines/table-engines/special/distributed).

        * `host_specs` — настройки хостов, которые будут добавлены в шард. Настройки представлены в виде массива элементов. Каждый элемент соответствует отдельному хосту и имеет следующую структуру:

          * `zone_id` — зона доступности.
          * `type` — тип хоста. В шарды добавляются только хосты `CLICKHOUSE`.
          * `subnet_id` — идентификатор подсети.
          * `assign_public_ip` — доступность хоста из интернета по публичному IP-адресу: `true` или `false`.
          * `shard_name` — имя шарда.

        * `copy_schema` — копирование схемы данных со случайной реплики одного из шардов на хосты нового шарда. Возможные значения: `true` или `false`.

          {% note warning %}
          
          Используйте копирование схемы данных, только если схема одинакова на всех шардах кластера.
          
          {% endnote %}

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

        ```bash
        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.yandexcloud.kz:443 \
          yandex.cloud.mdb.clickhouse.v1.ClusterService.AddShards \
          < body.json
        ```

  1. Убедитесь, что запрос был выполнен успешно, изучив [ответ сервера](../api-ref/grpc/Cluster/addShards.md#yandex.cloud.operation.Operation).

{% endlist %}

## Получить список шардов в кластере {#list-shards}

{% list tabs group=instructions %}

- Консоль управления {#console}

  1. В [консоли управления](https://kz.console.yandex.cloud) выберите каталог, в котором находится кластер.
  1. Перейдите в сервис **Managed Service for&nbsp;ClickHouse**.
  1. Нажмите на имя нужного кластера, затем выберите вкладку **Шарды**.

- CLI {#cli}

  Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), [установите и инициализируйте его](../../cli/quickstart.md#install).

  По умолчанию используется каталог, указанный при [создании](../../cli/operations/profile/profile-create.md) профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду `yc config set folder-id <идентификатор_каталога>`. Также для любой команды вы можете указать другой каталог с помощью параметров `--folder-name` или `--folder-id`. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

  Чтобы получить список шардов в кластере, выполните команду:

  ```bash
  yc managed-clickhouse shards list --cluster-name=<имя_кластера>
  ```

  Имя кластера можно запросить со [списком кластеров в каталоге](cluster-list.md#list-clusters).

- REST API {#api}

  1. [Получите IAM-токен для аутентификации в API](../api-ref/authentication.md) и поместите токен в переменную среды окружения:

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

  1. Воспользуйтесь методом [Cluster.ListShards](../api-ref/Cluster/listShards.md) и выполните запрос, например с помощью [cURL](https://curl.se/):

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

     Идентификатор кластера можно запросить со [списком кластеров в каталоге](cluster-list.md#list-clusters).

  1. Убедитесь, что запрос был выполнен успешно, изучив [ответ сервера](../api-ref/Cluster/listShards.md#yandex.cloud.mdb.clickhouse.v1.ListClusterShardsResponse).

- gRPC API {#grpc-api}

  1. [Получите IAM-токен для аутентификации в API](../api-ref/authentication.md) и поместите токен в переменную среды окружения:

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

  1. Клонируйте репозиторий [cloudapi](https://github.com/yandex-cloud/cloudapi):
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Далее предполагается, что содержимое репозитория находится в директории `~/cloudapi/`.
  1. Воспользуйтесь вызовом [ClusterService.ListShards](../api-ref/grpc/Cluster/listShards.md) и выполните запрос, например с помощью [gRPCurl](https://github.com/fullstorydev/grpcurl):

     ```bash
     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.yandexcloud.kz:443 \
       yandex.cloud.mdb.clickhouse.v1.ClusterService.ListShards
     ```

     Идентификатор кластера можно запросить со [списком кластеров в каталоге](cluster-list.md#list-clusters).

  1. Убедитесь, что запрос был выполнен успешно, изучив [ответ сервера](../api-ref/grpc/Cluster/listShards.md#yandex.cloud.mdb.clickhouse.v1.ListClusterShardsResponse).

{% endlist %}

## Изменить шард {#shard-update}

Вы можете изменить вес шарда, а также [класс хоста](../concepts/instance-types.md), [тип диска](../concepts/storage.md) и размер хранилища.

{% note warning %}

При изменении типа диска хосты кластера пересоздаются. Данные реплицированных таблиц сохраняются автоматически. Данные нереплицированных таблиц будут потеряны. Если необходимо сохранить данные в нереплицированных таблицах, перед изменением типа диска [преобразуйте их в реплицированные](https://clickhouse.com/docs/ru/sql-reference/statements/attach#attach-mergetree-table-as-replicatedmergetree).

{% endnote %}

{% list tabs group=instructions %}

- Консоль управления {#console}

  1. В [консоли управления](https://kz.console.yandex.cloud) выберите каталог, в котором находится кластер.
  1. Перейдите в сервис **Managed Service for&nbsp;ClickHouse**.
  1. Нажмите на имя нужного кластера, затем выберите вкладку **Шарды**.
  1. Нажмите ![horizontal-ellipsis](../../_assets/console-icons/ellipsis.svg) и выберите пункт **Редактировать**.
  1. Внесите необходимые изменения и нажмите кнопку **Сохранить изменения**.
  1. Если вы изменили тип диска для шарда с хостами ClickHouse®:
      1. В открывшемся окне посмотрите количество нереплицированных таблиц на графике **Non-replicated MergeTree tables** и их размер на графике **Size of non-replicated MergeTree tables**. Данные в нереплицированных таблицах будут утеряны. Если необходимо сохранить их, перед изменением типа диска [преобразуйте](https://clickhouse.com/docs/ru/sql-reference/statements/attach#attach-mergetree-table-as-replicatedmergetree) нереплицированные таблицы в реплицированные.
      1. Подтвердите изменение ресурсов.

- CLI {#cli}

  Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), [установите и инициализируйте его](../../cli/quickstart.md#install).

  По умолчанию используется каталог, указанный при [создании](../../cli/operations/profile/profile-create.md) профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду `yc config set folder-id <идентификатор_каталога>`. Также для любой команды вы можете указать другой каталог с помощью параметров `--folder-name` или `--folder-id`. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

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

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

     ```bash
     yc managed-clickhouse shards update --help
     ```

  1. Передайте в команде параметры, которые вы хотите изменить:

     ```bash
     yc managed-clickhouse shards update <имя_шарда> \
       --cluster-name <имя_кластера> \
       --weight <вес_шарда> \
       --clickhouse-resource-preset <класс_хостов> \
       --clickhouse-disk-size <размер_хранилища> \
       --clickhouse-disk-type <тип_диска> \
       --allow-host-recreation
     ```

     Где:

     * `--cluster-name` — имя кластера. Его можно запросить со [списком кластеров в каталоге](cluster-list.md#list-clusters).
     * `--weight` — вес шарда. Минимальное значение — `0`.
     * `--clickhouse-resource-preset` — [класс хостов](../concepts/instance-types.md).
     * `--clickhouse-disk-size` — размер хранилища в гигабайтах.
     * `--clickhouse-disk-type` — [тип диска](../concepts/storage.md).
     * `--allow-host-recreation` — разрешить кластеру пересоздать хосты (параметр обязателен при изменении типа диска).

     Имя шарда можно запросить со [списком шардов в кластере](#list-shards).

- REST API {#api}

  1. [Получите IAM-токен для аутентификации в API](../api-ref/authentication.md) и поместите токен в переменную среды окружения:

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

  1. Воспользуйтесь методом [Cluster.UpdateShard](../api-ref/Cluster/updateShard.md) и выполните запрос, например с помощью [cURL](https://curl.se/):

     {% note warning %}
     
     Метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре `updateMask` (одной строкой через запятую).
     
     {% endnote %}

     ```bash
     curl \
         --request PATCH \
         --header "Authorization: Bearer $IAM_TOKEN" \
         --header "Content-Type: application/json" \
         --url 'https://mdb.api.yandexcloud.kz/managed-clickhouse/v1/clusters/<идентификатор_кластера>/shards/<имя_шарда>' \
         --data '{
                   "updateMask": "configSpec.clickhouse.config.<настройка_ClickHouse®>,configSpec.clickhouse.resources,configSpec.clickhouse.weight,allowHostRecreation",
                   "configSpec": {
                     "clickhouse": {
                       "config": {
                         <настройки_ClickHouse®>
                       },
                       "resources": {
                         "resourcePresetId": "<класс_хостов>",
                         "diskSize": "<размер_хранилища_в_байтах>",
                         "diskTypeId": "<тип_диска>"
                       },
                       "weight": "<вес_шарда>"
                     }
                   },
                   "allowHostRecreation": "true"
                 }'
     ```

     Где:

     * `updateMask` — перечень изменяемых параметров в одну строку через запятую.
     * `configSpec.clickhouse` — изменяемые параметры шарда:

       * `config` — [настройки ClickHouse®](../concepts/settings-list.md). Список доступных настроек приведен в [описании метода](../api-ref/Cluster/updateShard.md#yandex.cloud.mdb.clickhouse.v1.UpdateClusterShardRequest).

       * `resources` — ресурсы хостов, которые добавляются в создаваемый шард:

         * `resourcePresetId` — идентификатор [класса хостов](../concepts/instance-types.md). Список доступных классов хостов с их идентификаторами можно запросить с помощью метода [ResourcePreset.List](../api-ref/ResourcePreset/list.md).
         * `diskSize` — размер диска в байтах.
         * `diskTypeId` — [тип диска](../concepts/storage.md).

       * `weight` — вес шарда.

         По умолчанию каждому шарду назначается вес `1`. Если какому-либо шарду назначить вес больше, данные будут распределены между шардами в соответствии с весами.

         При расчете приоритета шарда при распределении данных складываются веса всех шардов, далее вес каждого шарда делится на полученную сумму. Например, если у одного шарда вес `1`, а у другого — `3`, то у первого шарда приоритет `1/4`, а у второго — `3/4`. Чем выше приоритет, тем больше данных окажется на шарде.

         Подробнее в [документации ClickHouse®](https://clickhouse.com/docs/ru/engines/table-engines/special/distributed).

     * `allowHostRecreation` — разрешить кластеру пересоздать хосты (параметр обязателен при изменении типа диска).

     Идентификатор кластера можно запросить со [списком кластеров в каталоге](cluster-list.md#list-clusters), а имя шарда — со [списком шардов в кластере](#list-shards).

  1. Убедитесь, что запрос был выполнен успешно, изучив [ответ сервера](../api-ref/Cluster/updateShard.md#yandex.cloud.operation.Operation).

- gRPC API {#grpc-api}

  1. [Получите IAM-токен для аутентификации в API](../api-ref/authentication.md) и поместите токен в переменную среды окружения:

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

  1. Клонируйте репозиторий [cloudapi](https://github.com/yandex-cloud/cloudapi):
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Далее предполагается, что содержимое репозитория находится в директории `~/cloudapi/`.
  1. Воспользуйтесь вызовом [ClusterService.UpdateShard](../api-ref/grpc/Cluster/updateShard.md) и выполните запрос, например с помощью [gRPCurl](https://github.com/fullstorydev/grpcurl):

     {% note warning %}
     
     Метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре `update_mask` (в виде массива строк `paths[]`).
     
     {% cut "Формат перечисления настроек" %}
     
     ```yaml
     "update_mask": {
         "paths": [
             "<настройка_1>",
             "<настройка_2>",
             ...
             "<настройка_N>"
         ]
     }
     ```
     
     {% endcut %}
     
     {% endnote %}

     ```bash
     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": "<идентификатор_кластера>",
             "shard_name": "<имя_шарда>",
             "update_mask": {
               "paths": [
                 "config_spec.clickhouse.config.<настройка_ClickHouse®>",
                 "config_spec.clickhouse.resources",
                 "config_spec.clickhouse.weight",
                 "allow_host_recreation"
               ]
             },
             "config_spec": {
               "clickhouse": {
                 "config": {
                   <настройки_ClickHouse®>
                 },
                 "resources": {
                   "resource_preset_id": "<класс_хостов>",
                   "disk_size": "<размер_хранилища_в_байтах>",
                   "disk_type_id": "<тип_диска>"
                 },
                 "weight": "<вес_шарда>"
               }
             },
             "allow_host_recreation": "true"
           }' \
       mdb.api.yandexcloud.kz:443 \
       yandex.cloud.mdb.clickhouse.v1.ClusterService.UpdateShard
     ```

     Где:

     * `update_mask` — перечень изменяемых параметров в виде массива строк `paths[]`.
     * `config_spec.clickhouse` — изменяемые параметры шарда:

       * `config` — [настройки ClickHouse®](../concepts/settings-list.md). Список доступных настроек приведен в [описании метода](../api-ref/Cluster/updateShard.md#yandex.cloud.mdb.clickhouse.v1.UpdateClusterShardRequest).

       * `resources` — ресурсы хостов, которые добавляются в создаваемый шард:

         * `resource_preset_id` — идентификатор [класса хостов](../concepts/instance-types.md). Список доступных классов хостов с их идентификаторами можно запросить с помощью метода [ResourcePreset.List](../api-ref/ResourcePreset/list.md).
         * `disk_size` — размер диска в байтах.
         * `disk_type_id` — [тип диска](../concepts/storage.md).

       * `weight` — вес шарда.

         По умолчанию каждому шарду назначается вес `1`. Если какому-либо шарду назначить вес больше, данные будут распределены между шардами в соответствии с весами.

         При расчете приоритета шарда при распределении данных складываются веса всех шардов, далее вес каждого шарда делится на полученную сумму. Например, если у одного шарда вес `1`, а у другого — `3`, то у первого шарда приоритет `1/4`, а у второго — `3/4`. Чем выше приоритет, тем больше данных окажется на шарде.

         Подробнее в [документации ClickHouse®](https://clickhouse.com/docs/ru/engines/table-engines/special/distributed).

     * `allow_host_recreation` — разрешить кластеру пересоздать хосты (параметр обязателен при изменении типа диска).

     Идентификатор кластера можно запросить со [списком кластеров в каталоге](cluster-list.md#list-clusters), а имя шарда — со [списком шардов в кластере](#list-shards).

  1. Убедитесь, что запрос был выполнен успешно, изучив [ответ сервера](../api-ref/grpc/Cluster/updateShard.md#yandex.cloud.operation.Operation).

{% endlist %}

## Удалить шард {#delete-shard}

Вы можете удалить шард из кластера ClickHouse®, если он не является:
* Единственным шардом.
* Единственным шардом в [группе шардов](shard-groups.md).

Удаление шарда приведет к удалению всех таблиц и данных, которые находятся на этом шарде.

{% list tabs group=instructions %}

- Консоль управления {#console}

    1. В [консоли управления](https://kz.console.yandex.cloud) выберите каталог, в котором находится кластер.
    1. Перейдите в сервис **Managed Service for&nbsp;ClickHouse**.
    1. Нажмите на имя нужного кластера и выберите вкладку **Шарды**.
    1. Удалите один или несколько шардов:
        * Чтобы удалить один шард, нажмите на значок ![image](../../_assets/console-icons/ellipsis.svg) в строке нужного шарда и выберите пункт **Удалить**.
        * Чтобы удалить несколько шардов сразу, выберите нужные шарды и нажмите **Удалить** в нижней части экрана.
    1. В открывшемся окне включите опцию **Я удаляю шарды** и нажмите кнопку **Удалить**.

- CLI {#cli}

  Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), [установите и инициализируйте его](../../cli/quickstart.md#install).

  По умолчанию используется каталог, указанный при [создании](../../cli/operations/profile/profile-create.md) профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду `yc config set folder-id <идентификатор_каталога>`. Также для любой команды вы можете указать другой каталог с помощью параметров `--folder-name` или `--folder-id`. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

  Чтобы удалить один или несколько шардов из кластера, выполните команду, передав нужные имена шардов. Используйте пробел в качестве разделителя.

  Команда для удаления одного шарда имеет вид:

  ```bash
  yc managed-clickhouse shards delete \
    --cluster-name=<имя_кластера> \
    <имя_шарда>
  ```

  Имена шардов можно запросить со [списком шардов в кластере](#list-shards), имя кластера — со [списком кластеров в каталоге](cluster-list.md#list-clusters).


- Terraform {#tf}

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

     О том, как создать такой файл, в разделе [Создание кластера](cluster-create.md).

  1. В описании кластера Managed Service for ClickHouse® удалите шард из блока `shards`, а из блока `hosts` — все хосты ClickHouse® на этом шарде.
  1. Проверьте корректность настроек.

     1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.
     1. Выполните команду:
     
        ```bash
        terraform validate
        ```
     
        Если в файлах конфигурации есть ошибки, Terraform на них укажет.

  1. Введите слово `yes` и нажмите **Enter**.

     1. Выполните команду для просмотра планируемых изменений:
     
        ```bash
        terraform plan
        ```
     
        Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.
     
     1. Если вас устраивают планируемые изменения, внесите их:
        1. Выполните команду:
     
           ```bash
           terraform apply
           ```
     
        1. Подтвердите изменение ресурсов.
        1. Дождитесь завершения операции.

  Подробнее в [документации провайдера Terraform](../../terraform/resources/mdb_clickhouse_cluster.md).

  {% note warning "Ограничения по времени" %}
  
  Провайдер Terraform ограничивает время на выполнение операций с кластером Managed Service for ClickHouse®:
  
  * создание, в т. ч. путем восстановления из резервной копии, — 60 минут;
  * изменение — 90 минут;
  * удаление — 30 минут.
  
  Операции, длящиеся дольше указанного времени, прерываются.
  
  {% cut "Как изменить эти ограничения?" %}
  
  Добавьте к описанию кластера блок `timeouts`, например:
  
  ```hcl
  resource "yandex_mdb_clickhouse_cluster_v2" "<имя_кластера>" {
    ...
    timeouts = {
      create = "1h30m" # Полтора часа
      update = "2h"    # 2 часа
      delete = "30m"   # 30 минут
    }
  }
  ```
  
  {% endcut %}
  
  {% endnote %}


- REST API {#api}

  1. [Получите IAM-токен для аутентификации в API](../api-ref/authentication.md) и поместите токен в переменную среды окружения:

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

  1. Воспользуйтесь методом [Cluster.DeleteShards](../api-ref/Cluster/deleteShards.md) и выполните запрос, например с помощью [cURL](https://curl.se/):

     ```bash
     curl \
       --request DELETE \
       --header "Authorization: Bearer $IAM_TOKEN" \
       --url 'https://mdb.api.yandexcloud.kz/managed-clickhouse/v1/clusters/<идентификатор_кластера>/shards:batchDelete' \
       --data '{
                 "shardNames": [
                   <перечень_имен_шардов>
                 ]
               }'
     ```

     Где `shardNames` — массив строк. Каждая строка — имя шарда, который нужно удалить. Имена шардов можно запросить со [списком шардов в кластере](#list-shards).

     Идентификатор кластера можно запросить со [списком кластеров в каталоге](cluster-list.md#list-clusters).

  1. Убедитесь, что запрос был выполнен успешно, изучив [ответ сервера](../api-ref/Cluster/deleteShard.md#yandex.cloud.operation.Operation).

- gRPC API {#grpc-api}

  1. [Получите IAM-токен для аутентификации в API](../api-ref/authentication.md) и поместите токен в переменную среды окружения:

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

  1. Клонируйте репозиторий [cloudapi](https://github.com/yandex-cloud/cloudapi):
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Далее предполагается, что содержимое репозитория находится в директории `~/cloudapi/`.
  1. Воспользуйтесь вызовом [ClusterService.DeleteShards](../api-ref/grpc/Cluster/deleteShards.md) и выполните запрос, например с помощью [gRPCurl](https://github.com/fullstorydev/grpcurl):

     ```bash
     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": "<идентификатор_кластера>",
             "shard_names": [
               <перечень_имен_шардов>
             ]
           }' \
       mdb.api.yandexcloud.kz:443 \
       yandex.cloud.mdb.clickhouse.v1.ClusterService.DeleteShards
     ```

     Где `shard_names` — массив строк. Каждая строка — имя шарда, который нужно удалить. Имена шардов можно запросить со [списком шардов в кластере](#list-shards).

     Идентификатор кластера можно запросить со [списком кластеров в каталоге](cluster-list.md#list-clusters).

  1. Убедитесь, что запрос был выполнен успешно, изучив [ответ сервера](../api-ref/grpc/Cluster/deleteShards.md#yandex.cloud.operation.Operation).

{% endlist %}

_ClickHouse® является зарегистрированным товарным знаком [ClickHouse, Inc](https://clickhouse.com)._