All Products
Search
Document Center

ApsaraDB for ClickHouse:DescribeDBClusters

Last Updated:Nov 12, 2024

Queries the information about ApsaraDB for ClickHouse clusters in a region.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
clickhouse:DescribeDBClustersget
  • All Resources
    *
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringYes

The region ID. You can call the DescribeRegions operation to query the most recent region list.

cn-hangzhou
DBClusterIdsstringNo

The cluster ID.

Note If you do not specify this parameter, the information about all clusters is queried.
cc-bp108z124a8o7****
DBClusterDescriptionstringNo

The description of the cluster.

cc-bp108z124a8o7****
DBClusterStatusstringNo

The state of the cluster. Valid values:

  • Preparing: The cluster is being prepared.
  • Creating: The cluster is being created.
  • Running: The cluster is running.
  • Deleting: The cluster is being deleted.
  • SCALING_OUT: The storage capacity of the cluster is being expanded.
Running
PageSizeintegerNo

The number of entries returned per page. Valid values:

  • 30 (default)
  • 50
  • 100
30
PageNumberintegerNo

The page number.

1
Tagarray<object>No

The tags.

objectNo
KeystringNo

The tag name.

department
ValuestringNo

The tag value.

it
ResourceGroupIdstringNo

The ID of the resource group to which the cluster belongs.

rg-4690g37929****

Response parameters

ParameterTypeDescriptionExample
object
TotalCountinteger

The total number of entries that are returned.

1
PageSizeinteger

The number of entries returned per page. Valid values:

  • 30 (default)
  • 50
  • 100
30
RequestIdstring

The request ID.

F5178C10-1407-4987-9133-DE4DC9119F75
PageNumberinteger

The total number of returned pages.

1
DBClustersarray<object>

The clusters.

DBClusterobject

The cluster.

VpcIdstring

The ID of the virtual private cloud (VPC) in which the cluster is deployed.

vpc-bp175iuvg8nxqraf2****
DBNodeCountlong

The number of nodes.

  • Valid values when the cluster is of Single-replica Edition: 1 to 48.
  • Valid values when the cluster is of Double-replica Edition: 1 to 24.
2
CreateTimestring

The time when the cluster was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format.

2021-10-28T07:24:45Z
PayTypestring

The billing method of the cluster. Valid values:

  • Postpaid: The cluster uses the pay-as-you-go billing method.
  • Prepaid: The cluster uses the subscription billing method.
Postpaid
Tagsarray<object>

The tags.

Tagobject
Keystring

The tag name.

department
Valuestring

The tag value.

it
StorageTypestring

The storage type of the cluster. Valid values:

  • CloudESSD: The cluster uses an enhanced SSD (ESSD) of performance level (PL) 1.
  • CloudESSD_PL2: The cluster uses an ESSD of PL 2.
  • CloudESSD_PL3: The cluster uses an ESSD of PL 3.
  • CloudEfficiency: The cluster uses an ultra disk.
CloudESSD
Portinteger

The HTTP port number.

8123
LockModestring

The lock mode of the cluster. Valid values:

  • Unlock: The cluster is not locked.
  • ManualLock: The cluster is manually locked.
  • LockByExpiration: The cluster is automatically locked due to cluster expiration.
  • LockByRestoration: The cluster is automatically locked because the cluster is about to be rolled back.
  • LockByDiskQuota: The cluster is automatically locked because the disk space is exhausted.
Unlock
Bidstring

The site ID. Valid values:

  • 26842: the China site (aliyun.com)
  • 26888: the international site (alibabacloud.com)
26842
IsExpiredstring

Indicates whether the cluster has expired. Valid values:

  • true: The cluster has expired.
  • false: The cluster has not expired.
false
VpcCloudInstanceIdstring

The ID of the VPC in which the cluster is deployed.

vpc-bp175iuvg8nxqraf2****
ScaleOutStatusobject

The status of a data migration task.

Progressstring

The progress of the data migration task in percentage.

Note This parameter is returned only when the cluster is in the SCALING_OUT state.
0
Ratiostring

The progress of the data migration task. This value is displayed in the following format: Data volume that has been migrated/Total data volume.

Note This parameter is returned only when the cluster is in the SCALING_OUT state.
0MB/60469MB
DBClusterIdstring

The cluster ID.

cc-bp108z124a8o7****
ConnectionStringstring

The VPC endpoint of the cluster.

cc-bp1fs5o051c61****.clickhouse.ads.aliyuncs.com
CommodityCodestring

The commodity code of the cluster.

clickhouse_go_public_cn
ExpireTimestring

The time when the cluster expired. The time is in the yyyy-MM-ddTHH:mm:ssZ format.

Note Pay-as-you-go clusters never expire. If the cluster is a pay-as-you-go cluster, an empty string is returned for this parameter.
2011-05-30T12:11:4Z
DBNodeStoragelong

The storage capacity of each node. Valid values: 100 to 32000. Unit: GB.

Note This value is a multiple of 100.
100
DBNodeClassstring

The specifications of the cluster.

  • Valid values when the cluster is of Single-replica Edition: -S4: 4 CPU cores and 16 GB of memory -S8: 8 CPU cores and 32 GB of memory

    • S16: 16 CPU cores and 64 GB of memory
    • S32: 32 CPU cores and 128 GB of memory
    • S64: 64 CPU cores and 256 GB of memory
    • S104: 104 CPU cores and 384 GB of memory
  • Valid values when the cluster is of Double-replica Edition: -C4: 4 CPU cores and 16 GB of memory -C8: 8 CPU cores and 32 GB of memory -C16: 16 CPU cores and 64 GB of memory -C32: 32 CPU cores and 128 GB of memory -C64: 64 CPU cores and 256 GB of memory -C104: 104 CPU cores and 384 GB of memory

C8
AliUidstring

The ID of the Alibaba Cloud account.

140692647406****
LockReasonstring

The cause why the cluster was locked.

Note If the value of the LockMode parameter is Unlock, an empty string is returned for this parameter.
DISK_FULL
RegionIdstring

The region ID.

cn-hangzhou
VSwitchIdstring

The vSwitch ID.

vsw-bp1gzt31twhlo0sa5****
DBClusterStatusstring

The state of the cluster. Valid values:

  • Preparing: The cluster is being prepared.
  • Creating: The cluster is being created.
  • Running: The cluster is running.
  • Deleting: The cluster is being deleted.
  • SCALING_OUT: The storage capacity of the cluster is being expanded.
Running
DBClusterDescriptionstring

The description of the cluster.

test
DBClusterNetworkTypestring

The network type of the cluster. Only VPC is supported.

VPC
ZoneIdstring

The zone ID.

cn-hangzhou-h
Categorystring

The edition of the cluster. Valid values:

  • Basic: Single-replica Edition
  • HighAvailability: Double-replica Edition
Basic
ControlVersionstring

The version number of the backend management system of ApsaraDB for ClickHouse. Valid values:

  • v1
  • v2
v1
ExtStorageTypestring

The extended storage type. Valid values:

  • CloudSSD: standard SSD.
  • CloudESSD: The cluster uses an enhanced SSD (ESSD) of performance level (PL) 1.
  • CloudESSD_PL2: The cluster uses an ESSD of PL 2.
  • CloudESSD_PL3: The cluster uses an ESSD of PL 3.
  • CloudEfficiency: The cluster uses an ultra disk.
CloudESSD
ExtStorageSizeinteger

The extended storage space.

100GB
ResourceGroupIdstring

The ID of the resource group to which the cluster belongs.

rg-4690g37929****

Examples

Sample success responses

JSONformat

{
  "TotalCount": 1,
  "PageSize": 30,
  "RequestId": "F5178C10-1407-4987-9133-DE4DC9119F75",
  "PageNumber": 1,
  "DBClusters": {
    "DBCluster": [
      {
        "VpcId": "vpc-bp175iuvg8nxqraf2****",
        "DBNodeCount": 2,
        "CreateTime": "2021-10-28T07:24:45Z",
        "PayType": "Postpaid",
        "Tags": {
          "Tag": [
            {
              "Key": "department",
              "Value": "it"
            }
          ]
        },
        "StorageType": "CloudESSD",
        "Port": 8123,
        "LockMode": "Unlock",
        "Bid": "26842",
        "IsExpired": "false",
        "VpcCloudInstanceId": "vpc-bp175iuvg8nxqraf2****",
        "ScaleOutStatus": {
          "Progress": "0",
          "Ratio": "0MB/60469MB"
        },
        "ScaleOutDisableWriteWindows": "",
        "DBClusterId": "cc-bp108z124a8o7****",
        "ConnectionString": "cc-bp1fs5o051c61****.clickhouse.ads.aliyuncs.com",
        "CommodityCode": "clickhouse_go_public_cn",
        "ExpireTime": "2011-05-30T12:11:4Z",
        "DBNodeStorage": 100,
        "DBNodeClass": "C8",
        "AliUid": "140692647406****",
        "LockReason": "DISK_FULL",
        "RegionId": "cn-hangzhou",
        "VSwitchId": "vsw-bp1gzt31twhlo0sa5****",
        "DBClusterStatus": "Running",
        "DBClusterDescription": "test",
        "DBClusterNetworkType": "VPC",
        "ZoneId": "cn-hangzhou-h",
        "Category": "Basic",
        "ControlVersion": "v1",
        "ExtStorageType": "CloudESSD",
        "ExtStorageSize": 0,
        "ResourceGroupId": "rg-4690g37929****",
        "DbVersion": ""
      }
    ]
  }
}

Error codes

HTTP status codeError codeError messageDescription
403ForbiddenUser not authorized to operate on the specified resource.The account is not granted permission to manipulate the resource
500InternalErrorAn error occurred while processing your request.An error occurred while processing your request.
503ServiceUnavailableAn error occurred while processing your request.An error occurred while processing your request.

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2024-09-03The Error code has changed. The response structure of the API has changedView Change Details
2024-06-24The Error code has changed. The response structure of the API has changedView Change Details
2023-11-06The Error code has changedView Change Details
2023-03-20The Error code has changed. The request parameters of the API has changed. The response structure of the API has changedView Change Details
2021-09-07The Error code has changed. The request parameters of the API has changedView Change Details