DescribeDBClusters-阿里云帮助中心

View the Data Lakehouse Edition clusters in the destination region.

Operation description

For a current list of service endpoints, see Service Endpoints.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

adb:DescribeDBClusters

list

*DBClusterLakeVersion

acs:adb:{#regionId}:{#accountId}:dbcluster/{#DBClusterId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID. Note You can call the DescribeRegions operation to query the IDs of available regions.	cn-hangzhou
DBClusterIds	string	No	The cluster ID. If you omit this parameter, the operation returns information about all clusters in the specified region.	amv-bp1r053byu48p****
DBClusterDescription	string	No	The cluster description. Cannot start with `http://` or `https://`. The description must be 2 to 256 characters long.	test
DBClusterStatus	string	No	The cluster status. Valid values: Preparing: The cluster is preparing. Creating: The cluster is being created. Running: The cluster is running. Deleting: The cluster is being deleted. Restoring: The cluster is being restored from a backup. ClassChanging: The cluster specifications are changing. NetAddressCreating: A network connection is being created for the cluster. NetAddressDeleting: The network connection of the cluster is being deleted. NetAddressModifying: The network connection of the cluster is being modified.	Running
PageSize	integer	No	The number of entries to return on each page. Valid values: 30 (default) 50 100	30
PageNumber	integer	No	The page number. The value must be a positive integer. Default value: 1.	1
ResourceGroupId	string	No	The ID of the resource group. If you omit this parameter, the operation returns information about clusters in all resource groups.	rg-4690g37929****
Tag	array<object>	No	The tags to filter clusters by.
	object	No	Information about a cluster tag.
Key	string	No	The tag key.	tag1
Value	string	No	The tag value.	test1
ProductVersion	string	No	The product version. Valid values: EnterpriseVersion: Enterprise edition. BasicVersion: Basic edition. Note If you omit this parameter, the operation returns clusters of all product versions.	BasicVersion
DBClusterVersion	string	No	The cluster version. Valid values: 3.0: Data Warehouse edition. 5.0 (default): Includes the Lakehouse, Enterprise, and Basic editions. All: All editions, including the Data Warehouse, Lakehouse, Enterprise, and Basic editions.	5.0

Response elements

Element	Type	Description	Example
	object
TotalCount	integer	The total number of entries returned.	1
PageSize	integer	The number of entries per page.	30
RequestId	string	The request ID.	A5EDBA27-AF3E-5966-9503-FD1557E19167
PageNumber	integer	The page number.	1
Items	object
DBCluster	array<object>	The details of the clusters.
	array<object>	The details of the cluster.
Expired	string	Indicates whether the subscription cluster has expired. Valid values: true: The cluster has expired. false: The cluster has not expired. Note If a subscription cluster expires, it is locked and may be released after a period of time. We recommend that you renew the cluster. For more information, see Renewal. This parameter is not returned for pay-as-you-go clusters.	false
CreateTime	string	The creation time of the cluster. The time is in UTC and formatted as yyyy-MM-ddTHH:mm:ssZ.	2022-04-01T09:50:18Z
PayType	string	The billing method of the cluster. Valid values: Postpaid: pay-as-you-go. Prepaid: subscription.	Prepaid
Mode	string	The mode of the cluster. A value of flexible indicates that the cluster is in elastic mode.	flexible
Port	string	The port number of the cluster.	3306
LockMode	string	The lock state of the cluster. Valid values: Unlock: The cluster is not locked. ManualLock: The cluster is manually locked. LockByExpiration: The cluster is automatically locked upon expiration.	Unlock
StorageResource	string	The amount of reserved storage resources. An AnalyticDB Compute Unit (ACU) is equivalent to 1 vCPU and 4 GB of memory. Storage resources are used for data read and write operations. Increasing storage resources can improve the read and write performance of the cluster.	24ACU
DBClusterId	string	The ID of the Data Lakehouse Edition cluster.	amv-bp163885f8q21****
ConnectionString	string	The public endpoint of the cluster.	amv-bp163885f8q21****.ads.aliyuncs.com
DBClusterType	string	The type of the cluster. A value of Common indicates a regular cluster.	Common
CommodityCode	string	The commodity code of the cluster. Valid values: ads: a pay-as-you-go cluster. ads_pre: a subscription cluster.	ads_pre
ExpireTime	string	The expiration time of the cluster. The time is in UTC and formatted as yyyy-MM-ddTHH:mm:ssZ. Note If the cluster has a subscription billing method, the actual expiration time is returned. If the cluster has a pay-as-you-go billing method, no value is returned.	2022-07-01T09:50:18Z
LockReason	string	The reason that the cluster is locked. Note This parameter is returned only when the cluster is locked. The value is fixed as instance_expired.	instance_expired
VPCId	string	The virtual private cloud (VPC) ID.	vpc-bp13h7uzhulpuxvnp****
RegionId	string	The ID of the region where the cluster resides.	cn-hangzhou
ComputeResource	string	The amount of reserved computing resources. An AnalyticDB Compute Unit (ACU) is equivalent to 1 vCPU and 4 GB of memory. Computing resources are used for data computation. You can increase computing resources to accelerate queries and elastically scale them based on the cluster performance.	16ACU
VSwitchId	string	The vSwitch ID.	vsw-bp1syh8vvw8yech7n****
DBVersion	string	The database engine version. The only supported version is 5.0.	5.0
DBClusterStatus	string	The status 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. Restoring: The cluster is being restored from a backup. ClassChanging: The cluster specifications are being changed. NetAddressCreating: A network connection is being created. NetAddressDeleting: A network connection is being deleted. NetAddressModifying: A network connection is being modified.	Running
ResourceGroupId	string	The ID of the resource group.	rg-acfmyiu4ekp****
DBClusterNetworkType	string	The network type of the cluster. The only supported network type is VPC.	VPC
DBClusterDescription	string	The description of the cluster.	adb_test
ZoneId	string	The ID of the zone where the cluster resides.	cn-hangzhou-h
Engine	string	The database engine of the cluster. The value is fixed as AnalyticDB.	AnalyticDB
ReservedACU	string	The amount of remaining reserved computing resources. An ACU is equivalent to 1 vCPU and 4 GB of memory.	32ACU
Tags	object
Tag	array<object>	The list of tags.
	object	The tags.
Key	string	The tag key. Note You can call the TagResources operation to add tags to the cluster.	tag1
Value	string	The tag value.	test1
Category	string	The edition of the cluster. This parameter is returned only for clusters in Data Warehouse Edition. Valid values: BASIC: Basic Edition in reserved mode. CLUSTER: Cluster Edition in reserved mode. MIXED_STORAGE: Elastic Mode Cluster Edition (New). Note For more information about cluster editions, see Product editions.	MIXED_STORAGE
InnerPort	string	The internal port of the cluster.	3306
VPCCloudInstanceId	string	The internal endpoint.	am-bp163885f8q21****-controller
InnerIp	string	The internal IP address of the cluster.	10.1.xx.xx
DtsJobId	string	The ID of the Data Transmission Service (DTS) synchronization task. This parameter is returned only for MySQL analysis instances. For more information, see Overview of MySQL analysis instances.	dtsb1578j90XXXX
ElasticIOResource	integer	The number of Elastic IO Units (EIUs). For more information, see EIU details. Note This parameter is returned only for clusters in elastic mode.	2
RdsInstanceId	string	The ID of the source ApsaraDB RDS instance. This parameter is returned only for MySQL analysis instances. For more information, see Overview of MySQL analysis instances.	rm-bp11q28kvl688****
ExecutorCount	string	The number of compute nodes in an elastic mode cluster.	1
DBNodeClass	string	The node specification. This parameter is returned only for clusters in Data Warehouse Edition.	E8
DiskType	string	The disk type of the cluster. Valid values: local_ssd: local SSD. cloud: standard cloud disk. cloud_ssd: SSD cloud disk. cloud_efficiency: ultra disk. cloud_essd: PL1 ESSD. cloud_essd2: PL2 ESSD. cloud_essd3: PL3 ESSD. Note For more information about ESSDs, see ESSD specifications.	cloud_essd
DBNodeStorage	integer	The storage capacity of the cluster. Unit: GB.	300
DBNodeCount	integer	The number of node groups.	2
TaskInfo	object	Information about the task.
Name	string	The name of the task.	analyticDBFlexibleScaleOut
Status	string	The status of the task. Valid values: NOT_RUN: The task is pending. RUNNING: The task is running. SUCCEED: The task is complete.	RUNNING
Progress	string	The task progress, specified as a percentage.	10%
StepList	object
StepList	array<object>	The steps of the task.
	object	The steps of the task.
StepName	string	The name of the step.	ApplyResource
StepDesc	string	The description of the step.	Apply resource
StepStatus	string	The status of the step. Valid values: NOT_RUN: The step is pending. RUNNING: The step is running. SUCCEED: The step is complete.	SUCCEED
StepProgress	string	The progress of the step, specified as a percentage.	50%
StartTime	string	The time when the step started. The time is formatted as YYYY-MM-DDThh:mm:ssZ.	2024-03-10T09:28:34Z
EndTime	string	The time when the step ended. The time is formatted as YYYY-MM-DDThh:mm:ssZ.	2024-03-10T10:28:34Z
ProductForm	string	The product form. Valid values: LegacyForm: The legacy form. IntegrationForm: The integrated form.	IntegrationForm
ProductVersion	string	The product version. Valid values: BasicVersion: Basic Edition. EnterpriseVersion: Enterprise Edition.	EnterpriseVersion
ReservedNodeSize	string	The resource specification of a single reserved node.	8ACU
ReservedNodeCount	integer	The number of reserved resource nodes.	1
AINodeSpec	string	The AI node specification.	ADB.MLGrand.5
AINodeNumber	integer	The number of AI nodes.	1

Examples

Success response

JSON format

{
  "TotalCount": 1,
  "PageSize": 30,
  "RequestId": "A5EDBA27-AF3E-5966-9503-FD1557E19167",
  "PageNumber": 1,
  "Items": {
    "DBCluster": [
      {
        "Expired": "false",
        "CreateTime": "2022-04-01T09:50:18Z",
        "PayType": "Prepaid",
        "Mode": "flexible",
        "Port": "3306",
        "LockMode": "Unlock",
        "StorageResource": "24ACU",
        "DBClusterId": "amv-bp163885f8q21****",
        "ConnectionString": "amv-bp163885f8q21****.ads.aliyuncs.com",
        "DBClusterType": "Common",
        "CommodityCode": "ads_pre",
        "ExpireTime": "2022-07-01T09:50:18Z",
        "LockReason": "instance_expired",
        "VPCId": "vpc-bp13h7uzhulpuxvnp****",
        "RegionId": "cn-hangzhou",
        "ComputeResource": "16ACU",
        "VSwitchId": "vsw-bp1syh8vvw8yech7n****",
        "DBVersion": "5.0",
        "DBClusterStatus": "Running",
        "ResourceGroupId": "rg-acfmyiu4ekp****",
        "DBClusterNetworkType": "VPC",
        "DBClusterDescription": "adb_test",
        "ZoneId": "cn-hangzhou-h",
        "Engine": "AnalyticDB",
        "ReservedACU": "32ACU",
        "Tags": {
          "Tag": [
            {
              "Key": "tag1",
              "Value": "test1"
            }
          ]
        },
        "Category": "MIXED_STORAGE",
        "InnerPort": "3306",
        "VPCCloudInstanceId": "am-bp163885f8q21****-controller",
        "InnerIp": "10.1.xx.xx",
        "DtsJobId": "dtsb1578j90XXXX",
        "ElasticIOResource": 2,
        "RdsInstanceId": "rm-bp11q28kvl688****",
        "ExecutorCount": "1",
        "DBNodeClass": "E8",
        "DiskType": "cloud_essd",
        "DBNodeStorage": 300,
        "DBNodeCount": 2,
        "TaskInfo": {
          "Name": "analyticDBFlexibleScaleOut",
          "Status": "RUNNING",
          "Progress": "10%",
          "StepList": {
            "StepList": [
              {
                "StepName": "ApplyResource",
                "StepDesc": "Apply resource",
                "StepStatus": "SUCCEED",
                "StepProgress": "50%",
                "StartTime": "2024-03-10T09:28:34Z",
                "EndTime": "2024-03-10T10:28:34Z"
              }
            ]
          }
        },
        "ProductForm": "IntegrationForm",
        "ProductVersion": "EnterpriseVersion",
        "ReservedNodeSize": "8ACU",
        "ReservedNodeCount": 1,
        "AINodeSpec": "ADB.MLGrand.5",
        "AINodeNumber": 1
      }
    ]
  }
}

Error codes

HTTP status code	Error code	Error message	Description
500	InternalError	An error occurred while processing your request.	An internal error occurred. Please try again later.
503	ServiceUnavailable	An error occurred while processing your request.	The system is unavailable. Please try again later.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.