[Yandex Cloud documentation](../../index.md) > [Yandex Managed Service for ClickHouse®](../index.md) > [Step-by-step guides](index.md) > Sharding > Managing shards

# Managing shards in a ClickHouse® cluster

You can enable sharding for a cluster, as well as add and configure individual shards.

## Enabling sharding {#enable}

Managed Service for ClickHouse® clusters are created with a single shard. To start sharding data, [add](#add-shard) one or more shards and [create](../tutorials/sharding.md#example) a distributed table.

## Creating a shard {#add-shard}

The number of shards in Managed Service for ClickHouse® clusters is limited by the CPU and RAM quotas available to database clusters in your cloud. To review current resource usage, open the [Quotas](https://console.yandex.cloud/cloud?section=quotas) page and find the **Managed Service for ClickHouse** section.

You can create multiple shards in a cluster in one go.

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
  1. Navigate to **Managed Service for ClickHouse**.
  1. Click the cluster name and navigate to the **Shards** tab.
  1. Click **Create shards**.
  1. Click ![pencil](../../_assets/console-icons/pencil.svg) next to the new shard to update its parameters:
      * Name and weight.
      * Configuration of shard hosts.
  1. Optionally, click **Add shard** to add more shards and specify their parameters.
  1. Optionally, click **Add host** to add more hosts and specify their parameters.
  1. To copy the schema from a random replica of one of the shard to the hosts of the new shards, select **Copy the data schema**.

      {% note warning %}
      
      Use data schema copying only if the schema is the same on all the cluster shards.
      
      {% endnote %}

  1. Click **Create shard**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To create one or multiple shards:

  1. View the description of the CLI command for creating shards:

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

  1. Run the command to create shards.

      Specify one or multiple `--shard` parameters in the command, one for each new shard.

      Here is an example of the command for creating a single shard (it does not use all available parameters):

      ```bash
      yc managed-clickhouse shards add \
        --cluster-name=<cluster_name> \
        --shard name=<new_shard_name>,`
               `weight=<shard_weight> \
        --host zone-id=<availability_zone>,`
              `subnet-name=<subnet_name>,`
              `shard-name=<shard_name> \
        --copy-schema
      ```

      Where:

      * `--cluster-name`: Cluster name.

          You can get the cluster name from the [list of clusters in your folder](cluster-list.md#list-clusters).

      * `--shard`: Shard parameters:

          * `name`: Shard name. It must be unique within the cluster.

              It may contain Latin letters, numbers, hyphens, and underscores. The name may be up to 63 characters long.

          * `weight`: Shard weight.

      * `--host`: Parameters of the host to add to the shard:

          
          * `zone-id`: [Availability zone](../../overview/concepts/geo-scope.md).
          * `subnet-name`: [Subnet name](../../vpc/concepts/network.md#subnet).


          * `shard-name`: Name of the shard to add the host to.

      * `--copy-schema`: Optional parameter that initiates copying of the data schema from a random replica of one of the shards to the hosts of the new shard.

          {% note warning %}
          
          Use data schema copying only if the schema is the same on all the cluster shards.
          
          {% endnote %}


- Terraform {#tf}

  1. Open the current Terraform configuration file with the infrastructure plan.

     For more on how to create such a file, see the [Creating a cluster](cluster-create.md) section.

  1. In the Managed Service for ClickHouse® cluster description, add a new shard to the `shards` section and a ClickHouse® host on that shard to the `hosts` section:

     ```hcl
     resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
       ...
       shards = {
         ...
         "<shard_name>" = {
           weight = <shard_weight>
         }
       }

       hosts = {
         ...
         <host_name> = {
           type       = "CLICKHOUSE"
           zone       = "<availability_zone>"
           subnet_id  = yandex_vpc_subnet.<subnet_in_availability_zone>.id
           shard_name = "<shard_name>"
         }
       }
     }
     ```

  1. Optionally, to copy the schema from a random replica of one of the shards to the hosts of the new shards, add `copy_schema_on_new_hosts` set to `true` to the cluster description.

     {% note warning %}
     
     Use data schema copying only if the schema is the same on all the cluster shards.
     
     {% endnote %}

  1. Make sure the settings are correct.

     1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
     1. Run this command:
     
        ```bash
        terraform validate
        ```
     
        Terraform will show any errors found in your configuration files.

  1. Confirm resource changes.

     1. Run this command to view the planned changes:
     
        ```bash
        terraform plan
        ```
     
        If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
     
     1. If everything looks correct, apply the changes:
        1. Run this command:
     
           ```bash
           terraform apply
           ```
     
        1. Confirm updating the resources.
        1. Wait for the operation to complete.

  For more information, see [this Terraform provider guide](../../terraform/resources/mdb_clickhouse_cluster.md).

  {% note warning "Timeouts" %}
  
  The Terraform provider sets the following timeouts for Managed Service for ClickHouse® cluster operations:
  
  * Creating a cluster, including by restoring from a backup: 60 minutes.
  * Updating a cluster: 90 minutes.
  * Deleting a cluster: 30 minutes.
  
  Operations exceeding the timeout are aborted.
  
  {% cut "How to change these limits" %}
  
  Add the `timeouts` section to your cluster description, such as the following:
  
  ```hcl
  resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
    ...
    timeouts = {
      create = "1h30m" # 1 hour 30 minutes
      update = "2h"    # 2 hours
      delete = "30m"   # 30 minutes
    }
  }
  ```
  
  {% endcut %}
  
  {% endnote %}


- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

     ```bash
     export IAM_TOKEN="<IAM_token>"
     ```

  1. Call the [Cluster.AddShards](../api-ref/Cluster/addShards.md) method, e.g., via the following [cURL](https://curl.se/) request:

     1. Create a file named `body.json` and paste the following code into it:

        ```json
        {
          "shardSpecs": [
            {
              "name": "<shard_name>",
              "configSpec": {
                "clickhouse": {
                  "resources": {
                    "resourcePresetId": "<host_class>",
                    "diskSize": "<storage_size_in_bytes>",
                    "diskTypeId": "<disk_type>"
                  },
                  "weight": "<shard_weight>"
                }
              }
            }
          ],
          "hostSpecs": [
            {
              "zoneId": "<availability_zone>",
              "type": "CLICKHOUSE",
              "subnetId": "<subnet_ID>",
              "assignPublicIp": <public_access_to_host>,
              "shardName": "<shard_name>"
            }
          ],
          "copySchema": <copying_data_schema>
        }
        ```

        Where:

        * `shardSpecs`: Settings of shards to add to the cluster as an array of elements, one per shard. Each element has the following structure:

          * `name`: Shard name.
          * `configSpec.clickhouse.resources`: Host resources to add to the new shard:

            * `resourcePresetId`: [Host class](../concepts/instance-types.md) ID. You can get the list of available host classes with their IDs using the [ResourcePreset.List](../api-ref/ResourcePreset/list.md) method.
            * `diskSize`: Disk size, in bytes.
            * `diskTypeId`: [Disk type](../concepts/storage.md).

        * `configSpec.clickhouse.weight`: Shard weight.

          By default, each shard is assigned a weight of `1`. If you assign a greater value to a single shard, data will be distributed across the shards according to their weights.

          To calculate the shard priority for data distribution, the system adds up the weights of all shards and then divides each shard's weight by the total. For example, if one shard has a weight of `1` and another has a weight of `3`, then the first shard's priority is `1/4` and the second shard's priority is `3/4`. The higher the priority, the more data the shard will get.

          For more information, see [this ClickHouse® guide](https://clickhouse.com/docs/enen/engines/table-engines/special/distributed).

        * `hostSpecs`: Settings of hosts to add to the shard. The settings appear as an array of elements, one per host. Each element has the following structure:

          * `zoneId`: Availability zone.
          * `type`: Host type. You can only add `CLICKHOUSE` hosts to your shards.
          * `subnetId`: Subnet ID.
          * `assignPublicIp`: Internet access to the host via a public IP address, `true` or `false`.
          * `shardName`: Shard name.

        * `copySchema`: Copying the data schema from a random replica of one of the shards to the hosts of the new shard. The possible values are `true` or `false`.

          {% note warning %}
          
          Use data schema copying only if the schema is the same on all the cluster shards.
          
          {% endnote %}

     1. Run this query:

        ```bash
        curl \
          --request POST \
          --header "Authorization: Bearer $IAM_TOKEN" \
          --header "Content-Type: application/json" \
          --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<cluster_ID>/shards:batchCreate' \
          --data '@body.json'
        ```

        You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

  1. Check the [server response](../api-ref/Cluster/addShards.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

     ```bash
     export IAM_TOKEN="<IAM_token>"
     ```

  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.
  1. Call the [ClusterService.AddShards](../api-ref/grpc/Cluster/addShards.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

     1. Create a file named `body.json` and paste the following code into it:

        ```json
        {
          "cluster_id": "<cluster_ID>",
          "shard_specs": [
            {
              "name": "<shard_name>",
              "config_spec": {
                "clickhouse": {
                  "resources": {
                    "resource_preset_id": "<host_class>",
                    "disk_size": "<storage_size_in_bytes>",
                    "disk_type_id": "<disk_type>"
                  },
                  "weight": "<shard_weight>"
                }
              }
            }
          ],
          "host_specs": [
            {
              "zone_id": "<availability_zone>",
              "type": "CLICKHOUSE",
              "subnet_id": "<subnet_ID>",
              "assign_public_ip": <public_access_to_host>,
              "shard_name": "<shard_name>"
            }
          ],
          "copy_schema": <copying_data_schema>
        }
        ```

        Where:

        * `cluster_id`: Cluster ID. You can get it from the [list of clusters in the folder](cluster-list.md#list-clusters).
        * `shard_specs`: Settings of shards to add to the cluster as an array of elements, one per shard. Each element has the following structure:

          * `name`: Shard name.
          * `config_spec.clickhouse.resources`: Host resources to add to the new shard:

            * `resource_preset_id`: [Host class](../concepts/instance-types.md) ID. You can get the list of available host classes with their IDs using the [ResourcePresetService.List](../api-ref/grpc/ResourcePreset/list.md) method.
            * `disk_size`: Disk size, in bytes.
            * `disk_type_id`: [Disk type](../concepts/storage.md).

          * `config_spec.clickhouse.weight`: Shard weight.

            By default, each shard is assigned a weight of `1`. If you assign a greater value to a single shard, data will be distributed across the shards according to their weights.

            To calculate the shard priority for data distribution, the system adds up the weights of all shards and then divides each shard's weight by the total. For example, if one shard has a weight of `1` and another has a weight of `3`, then the first shard's priority is `1/4` and the second shard's priority is `3/4`. The higher the priority, the more data the shard will get.

            For more information, see [this ClickHouse® guide](https://clickhouse.com/docs/enen/engines/table-engines/special/distributed).

        * `host_specs`: Settings of hosts to add to the shard as an array of elements, one per host. Each element has the following structure:

          * `zone_id`: Availability zone.
          * `type`: Host type. You can only add `CLICKHOUSE` hosts to your shards.
          * `subnet_id`: Subnet ID.
          * `assign_public_ip`: Internet access to the host via a public IP address, `true` or `false`.
          * `shard_name`: Shard name.

        * `copy_schema`: Copying the data schema from a random replica of one of the shards to the hosts of the new shard. The possible values are `true` or `false`.

          {% note warning %}
          
          Use data schema copying only if the schema is the same on all the cluster shards.
          
          {% endnote %}

     1. Run this query:

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

  1. Check the [server response](../api-ref/grpc/Cluster/addShards.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

## Getting a list of cluster shards {#list-shards}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
  1. Navigate to **Managed Service for&nbsp;ClickHouse**.
  1. Click the name of your cluster and select the **Shards** tab.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To get a list of cluster shards, run this command:

  ```bash
  yc managed-clickhouse shards list --cluster-name=<cluster_name>
  ```

  You can get the cluster name with the [list of clusters in the folder](cluster-list.md#list-clusters).

- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

     ```bash
     export IAM_TOKEN="<IAM_token>"
     ```

  1. Call the [Cluster.ListShards](../api-ref/Cluster/listShards.md) method, e.g., via the following [cURL](https://curl.se/) request:

     ```bash
     curl \
       --request GET \
       --header "Authorization: Bearer $IAM_TOKEN" \
       --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<cluster_ID>/shards'
     ```

     You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

  1. Check the [server response](../api-ref/Cluster/listShards.md#yandex.cloud.mdb.clickhouse.v1.ListClusterShardsResponse) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

     ```bash
     export IAM_TOKEN="<IAM_token>"
     ```

  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.
  1. Call the [ClusterService.ListShards](../api-ref/grpc/Cluster/listShards.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

     ```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": "<cluster_ID>"
           }' \
       mdb.api.cloud.yandex.net:443 \
       yandex.cloud.mdb.clickhouse.v1.ClusterService.ListShards
     ```

     You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

  1. View the [server response](../api-ref/grpc/Cluster/listShards.md#yandex.cloud.mdb.clickhouse.v1.ListClusterShardsResponse) to make sure your request was successful.

{% endlist %}

## Updating a shard {#shard-update}

You can edit the shard weight as well as the [host class](../concepts/instance-types.md), [disk type](../concepts/storage.md), and storage size.

{% note warning %}

When you change the disk type, the cluster hosts get recreated. The system automatically saves the replicated tables data. The non-replicated tables data will be lost. If you need to preserve data in non-replicated tables, [convert it to replicated](https://clickhouse.com/docs/enen/sql-reference/statements/attach#attach-mergetree-table-as-replicatedmergetree) before you change the disk type.

{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
  1. Navigate to **Managed Service for&nbsp;ClickHouse**.
  1. Click the name of your cluster and select the **Shards** tab.
  1. Click ![horizontal-ellipsis](../../_assets/console-icons/ellipsis.svg) and select **Edit**.
  1. Edit as needed and click **Save changes**.
  1. If you changed the disk type for a shard with ClickHouse® hosts:
      1. In the window that opens, view the number of non-replicated tables in the **Non-replicated MergeTree tables** chart and their size in **Size of non-replicated MergeTree tables**. The data in non-replicated tables will be lost. If you need to keep it, [convert](https://clickhouse.com/docs/enen/sql-reference/statements/attach#attach-mergetree-table-as-replicatedmergetree) your non-replicated tables to replicated ones before changing the disk type.
      1. Confirm resource changes.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To update a shard in a cluster:

  1. View the description of the CLI command for updating a shard:

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

  1. Provide the parameters you want to edit to the command:

     ```bash
     yc managed-clickhouse shards update <shard_name> \
       --cluster-name <cluster_name> \
       --weight <shard_weight> \
       --clickhouse-resource-preset <host_class> \
       --clickhouse-disk-size <storage_size> \
       --clickhouse-disk-type <disk_type> \
       --allow-host-recreation
     ```

     Where:

     * `--cluster-name`: Cluster name. You can get it with the [list of clusters in the folder](cluster-list.md#list-clusters).
     * `--weight`: Shard weight. The minimum value is `0`.
     * `--clickhouse-resource-preset`: [Host class](../concepts/instance-types.md).
     * `--clickhouse-disk-size`: Storage size, in GB.
     * `--clickhouse-disk-type`: [Disk type](../concepts/storage.md).
     * `--allow-host-recreation`: Allows your cluster to recreate hosts. This setting is required when changing the disk type.

     You can get the shard name with the [list of shards in the cluster](#list-shards).

- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

     ```bash
     export IAM_TOKEN="<IAM_token>"
     ```

  1. Call the [Cluster.UpdateShard](../api-ref/Cluster/updateShard.md) method, e.g., via the following [cURL](https://curl.se/) request:

     {% note warning %}
     
     The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `updateMask` parameter as a single comma-separated string.
     
     {% endnote %}

     ```bash
     curl \
         --request PATCH \
         --header "Authorization: Bearer $IAM_TOKEN" \
         --header "Content-Type: application/json" \
         --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<cluster_ID>/shards/<shard_name>' \
         --data '{
                   "updateMask": "configSpec.clickhouse.config.<ClickHouse®_setup>,configSpec.clickhouse.resources,configSpec.clickhouse.weight,allowHostRecreation",
                   "configSpec": {
                     "clickhouse": {
                       "config": {
                         <ClickHouse®_settings>
                       },
                       "resources": {
                         "resourcePresetId": "<host_class>",
                         "diskSize": "<storage_size_in_bytes>",
                         "diskTypeId": "<disk_type>"
                       },
                       "weight": "<shard_weight>"
                     }
                   },
                   "allowHostRecreation": "true"
                 }'
     ```

     Where:

     * `updateMask`: Comma-separated string of settings to update.
     * `configSpec.clickhouse`: Shard parameters to update:

       * `config`: [ClickHouse® settings](../concepts/settings-list.md). For a list of available settings, see the [method description](../api-ref/Cluster/updateShard.md#yandex.cloud.mdb.clickhouse.v1.UpdateClusterShardRequest).

       * `resources`: Host resources to add to the new shard:

         * `resourcePresetId`: [Host class](../concepts/instance-types.md) ID. You can get the list of available host classes with their IDs using the [ResourcePreset.List](../api-ref/ResourcePreset/list.md) method.
         * `diskSize`: Disk size, in bytes.
         * `diskTypeId`: [Disk type](../concepts/storage.md).

       * `weight`: Shard weight.

         By default, each shard is assigned a weight of `1`. If you assign a greater value to a single shard, data will be distributed across the shards according to their weights.

         To calculate the shard priority for data distribution, the system adds up the weights of all shards and then divides each shard's weight by the total. For example, if one shard has a weight of `1` and another has a weight of `3`, then the first shard's priority is `1/4` and the second shard's priority is `3/4`. The higher the priority, the more data the shard will get.

         For more information, see [this ClickHouse® guide](https://clickhouse.com/docs/enen/engines/table-engines/special/distributed).

     * `allowHostRecreation`: Allows your cluster to recreate hosts. This setting is required when changing the disk type.

     You can get the cluster ID from the [list of clusters in your folder](cluster-list.md#list-clusters), and the shard name from the [list of cluster shards](#list-shards).

  1. Check the [server response](../api-ref/Cluster/updateShard.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

     ```bash
     export IAM_TOKEN="<IAM_token>"
     ```

  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.
  1. Call the [ClusterService.UpdateShard](../api-ref/grpc/Cluster/updateShard.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

     {% note warning %}
     
     The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `update_mask` parameter as an array of `paths[]` strings.
     
     {% cut "Format for listing settings" %}
     
     ```yaml
     "update_mask": {
         "paths": [
             "<setting_1>",
             "<setting_2>",
             ...
             "<setting_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": "<cluster_ID>",
             "shard_name": "<shard_name>",
             "update_mask": {
               "paths": [
                 "config_spec.clickhouse.config.<ClickHouse®_setup>",
                 "config_spec.clickhouse.resources",
                 "config_spec.clickhouse.weight",
                 "allow_host_recreation"
               ]
             },
             "config_spec": {
               "clickhouse": {
                 "config": {
                   <ClickHouse®_settings>
                 },
                 "resources": {
                   "resource_preset_id": "<host_class>",
                   "disk_size": "<storage_size_in_bytes>",
                   "disk_type_id": "<disk_type>"
                 },
                 "weight": "<shard_weight>"
               }
             },
             "allow_host_recreation": "true"
           }' \
       mdb.api.cloud.yandex.net:443 \
       yandex.cloud.mdb.clickhouse.v1.ClusterService.UpdateShard
     ```

     Where:

     * `update_mask`: List of settings to update as an array of strings (`paths[]`).
     * `config_spec.clickhouse`: Shard parameters to update:

       * `config`: [ClickHouse® settings](../concepts/settings-list.md). For a list of available settings, see the [method description](../api-ref/Cluster/updateShard.md#yandex.cloud.mdb.clickhouse.v1.UpdateClusterShardRequest).

       * `resources`: Host resources to add to the new shard:

         * `resource_preset_id`: [Host class](../concepts/instance-types.md) ID. You can get the list of available host classes with their IDs using the [ResourcePreset.List](../api-ref/ResourcePreset/list.md) method.
         * `disk_size`: Disk size, in bytes.
         * `disk_type_id`: [Disk type](../concepts/storage.md).

       * `weight`: Shard weight.

         By default, each shard is assigned a weight of `1`. If you assign a greater value to a single shard, data will be distributed across the shards according to their weights.

         To calculate the shard priority for data distribution, the system adds up the weights of all shards and then divides each shard's weight by the total. For example, if one shard has a weight of `1` and another has a weight of `3`, then the first shard's priority is `1/4` and the second shard's priority is `3/4`. The higher the priority, the more data the shard will get.

         For more information, see [this ClickHouse® guide](https://clickhouse.com/docs/enen/engines/table-engines/special/distributed).

     * `allow_host_recreation`: Allows your cluster to recreate hosts. This setting is required when changing the disk type.

     You can get the cluster ID from the [list of clusters in your folder](cluster-list.md#list-clusters), and the shard name from the [list of cluster shards](#list-shards).

  1. View the [server response](../api-ref/grpc/Cluster/updateShard.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

## Deleting a shard {#delete-shard}

You can delete a shard from a ClickHouse® cluster in case:
* It is not the only shard.
* It is not the only shard in a [shard group](shard-groups.md).

Deleting a shard will delete all tables and data stored on that shard.

{% list tabs group=instructions %}

- Management console {#console}

    1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
    1. Navigate to **Managed Service for&nbsp;ClickHouse**.
    1. Click the name of your cluster and select the **Shards** tab.
    1. Delete one or multiple shards:
        * To delete one shard, click ![image](../../_assets/console-icons/ellipsis.svg) in its row, and select **Delete**.
        * To delete multiple shards in one go, select them and click **Delete** at the bottom of the screen.
    1. In the window that opens, enable **Delete shards** and click **Delete**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To delete one or multiple shards from a cluster, run the command below, providing the names of the shards you want to delete. Use the space character as a separator.

  The command for deleting a single shard is as follows:

  ```bash
  yc managed-clickhouse shards delete \
    --cluster-name=<cluster_name> \
    <shard_name>
  ```

  You can get the shard names from the [list of cluster shards](#list-shards), and the cluster name, from the [list of clusters in your folder](cluster-list.md#list-clusters).


- Terraform {#tf}

  1. Open the current Terraform configuration file with the infrastructure plan.

     For more on how to create such a file, see the [Creating a cluster](cluster-create.md) section.

  1. In the Managed Service for ClickHouse® cluster description, delete the shard from the `shards` section, and all ClickHouse® hosts on that shard, from the `hosts` section.
  1. Make sure the settings are correct.

     1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
     1. Run this command:
     
        ```bash
        terraform validate
        ```
     
        Terraform will show any errors found in your configuration files.

  1. Type `yes` and press **Enter**.

     1. Run this command to view the planned changes:
     
        ```bash
        terraform plan
        ```
     
        If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
     
     1. If everything looks correct, apply the changes:
        1. Run this command:
     
           ```bash
           terraform apply
           ```
     
        1. Confirm updating the resources.
        1. Wait for the operation to complete.

  For more information, see [this Terraform provider guide](../../terraform/resources/mdb_clickhouse_cluster.md).

  {% note warning "Timeouts" %}
  
  The Terraform provider sets the following timeouts for Managed Service for ClickHouse® cluster operations:
  
  * Creating a cluster, including by restoring from a backup: 60 minutes.
  * Updating a cluster: 90 minutes.
  * Deleting a cluster: 30 minutes.
  
  Operations exceeding the timeout are aborted.
  
  {% cut "How to change these limits" %}
  
  Add the `timeouts` section to your cluster description, such as the following:
  
  ```hcl
  resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
    ...
    timeouts = {
      create = "1h30m" # 1 hour 30 minutes
      update = "2h"    # 2 hours
      delete = "30m"   # 30 minutes
    }
  }
  ```
  
  {% endcut %}
  
  {% endnote %}


- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

     ```bash
     export IAM_TOKEN="<IAM_token>"
     ```

  1. Call the [Cluster.DeleteShards](../api-ref/Cluster/deleteShards.md) method, e.g., via the following [cURL](https://curl.se/) request:

     ```bash
     curl \
       --request DELETE \
       --header "Authorization: Bearer $IAM_TOKEN" \
       --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<cluster_ID>/shards:batchDelete' \
       --data '{
                 "shardNames": [
                   <list_of_shard_names>
                 ]
               }'
     ```

     Where `shardNames` is an array of strings. Each string is the name of a shard to delete. You can get the shard names with the [list of shards in the cluster](#list-shards).

     You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

  1. Check the [server response](../api-ref/Cluster/deleteShard.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

     ```bash
     export IAM_TOKEN="<IAM_token>"
     ```

  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.
  1. Call the [ClusterService.DeleteShards](../api-ref/grpc/Cluster/deleteShards.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

     ```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": "<cluster_ID>",
             "shard_names": [
               <list_of_shard_names>
             ]
           }' \
       mdb.api.cloud.yandex.net:443 \
       yandex.cloud.mdb.clickhouse.v1.ClusterService.DeleteShards
     ```

     Where `shard_names` is an array of strings. Each string is the name of a shard to delete. You can get the shard names with the [list of shards in the cluster](#list-shards).

     You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

  1. Check the [server response](../api-ref/grpc/Cluster/deleteShards.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

_ClickHouse® is a registered trademark of [ClickHouse, Inc](https://clickhouse.com)._