Call DescribeDBClusters to query cluster information - AnalyticDB

List Data Lakehouse Edition clusters in the destination region.

Operation description

For the current service endpoint, see endpoint.

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	Region ID. Note Call the DescribeRegions operation to view region IDs.	cn-hangzhou
DBClusterIds	string	No	Data Lakehouse Edition cluster ID. If you do not specify this parameter, the system returns information about all clusters in the region by default.	amv-bp1r053byu48p****
DBClusterDescription	string	No	Cluster description. Must not start with `http://` or `https://`. Length: 2 to 256 characters.	test
DBClusterStatus	string	No	Cluster status. Valid values: Preparing: Preparing. Creating: Creating. Running: Running. Deleting: Deleting. Restoring: Restoring backup. ClassChanging: Upgrading or downgrading. NetAddressCreating: Creating network address. NetAddressDeleting: Deleting network address. NetAddressModifying: Modifying network address.	Running
PageSize	integer	No	Number of entries per page. Valid values: 30 (default) 50 100	30
PageNumber	integer	No	Page number. Valid values: positive integers greater than 0 and less than or equal to the maximum value of the integer data type. Default value: 1.	1
ResourceGroupId	string	No	If you do not specify this parameter, the system returns information about all resource groups in the cluster by default.	rg-4690g37929****
Tag	array<object>	No	Cluster tags.
	object	No	Cluster tag information.
Key	string	No	Tag key.	tag1
Value	string	No	Tag value.	test1
ProductVersion	string	No	Product version. Valid values: EnterpriseVersion: Enterprise Edition. BasicVersion: Basic Edition. Note This is an optional parameter. If you do not specify it, the system returns information about all clusters by default.	BasicVersion
DBClusterVersion	string	No	Cluster version. Valid values: 3.0: Data Warehouse Edition. 5.0 (default): Data Lakehouse Edition, Enterprise Edition, and Basic Edition. All: All versions, including Data Warehouse Edition, Data Lakehouse Edition, Enterprise Edition, and Basic Edition.	5.0

Response elements

Element	Type	Description	Example
	object
TotalCount	integer	Total number of entries.	1
PageSize	integer	Number of entries per page.	30
RequestId	string	Request ID.	A5EDBA27-AF3E-5966-9503-FD1557E19167
PageNumber	integer	Page number.	1
Items	object
DBCluster	array<object>	Detailed list information.
	array<object>	Cluster list.
Expired	string	Indicates whether a subscription cluster has expired. Valid values: true: Expired. false: Not expired. Note If a cluster expires, it may be locked or released after a grace period. We recommend that you renew your subscription. For more information, see Renewal policy. This parameter is not returned for pay-as-you-go clusters.	false
CreateTime	string	Time when the cluster was created, in UTC. Format: yyyy-MM-ddTHH:mm:ssZ.	2022-04-01T09:50:18Z
PayType	string	Payment type. Valid values: Postpaid: Pay-as-you-go. Prepaid: Subscription.	Prepaid
Mode	string	Cluster mode. Default value: flexible, which indicates an elastic-mode cluster.	flexible
Port	string	Cluster port number.	3306
LockMode	string	Cluster lock status. Valid values: Unlock: Unlocked. ManualLock: Manually locked. LockByExpiration: Locked due to expiration.	Unlock
StorageResource	string	Reserved storage resource specification. One ACU equals approximately one vCPU and 4 GB of memory. Storage resources are used for data read and write operations. Increasing this resource improves cluster read and write performance.	24ACU
DBClusterId	string	Data Lakehouse Edition cluster ID.	amv-bp163885f8q21****
ConnectionString	string	Public endpoint of the cluster.	amv-bp163885f8q21****.ads.aliyuncs.com
DBClusterType	string	Cluster type. Default value: Common, which indicates a standard cluster.	Common
CommodityCode	string	Commodity payment type. Valid values: ads: Pay-as-you-go commodity. ads_pre: Subscription commodity.	ads_pre
ExpireTime	string	Time when the cluster expires, in UTC. Format: yyyy-MM-ddTHH:mm:ssZ. Note This parameter returns the actual expiration time if the cluster uses the subscription billing method. This parameter returns an empty string if the cluster uses the pay-as-you-go billing method.	2022-07-01T09:50:18Z
LockReason	string	Reason why the cluster is locked. Note This parameter is returned only when the cluster is locked. Its value is always instance_expire.	instance_expired
VPCId	string	Virtual private cloud (VPC) ID.	vpc-bp13h7uzhulpuxvnp****
RegionId	string	Region ID where the cluster resides.	cn-hangzhou
ComputeResource	string	Reserved compute resource specification. One ACU equals approximately one vCPU and 4 GB of memory. Compute resources are used for data processing. Increasing compute resources speeds up queries. You can scale these resources up or down based on your cluster's performance needs.	16ACU
VSwitchId	string	vSwitch ID.	vsw-bp1syh8vvw8yech7n****
DBVersion	string	Database version. Only version 5.0 is supported.	5.0
DBClusterStatus	string	Cluster status. Valid values: Preparing: Preparing. Creating: Creating. Running: Running. Deleting: Deleting. Restoring: Restoring backup. ClassChanging: Upgrading or downgrading. NetAddressCreating: Creating network address. NetAddressDeleting: Deleting network address. NetAddressModifying: Modifying network address.	Running
ResourceGroupId	string	Resource group ID.	rg-acfmyiu4ekp****
DBClusterNetworkType	string	Cluster network type. Only VPC is supported.	VPC
DBClusterDescription	string	Cluster description.	adb_test
ZoneId	string	Zone ID where the cluster resides.	cn-hangzhou-h
Engine	string	Cluster engine. Fixed value: AnalyticDB.	AnalyticDB
ReservedACU	string	Remaining reserved compute resources available for allocation. One ACU equals approximately one vCPU and 4 GB of memory.	32ACU
Tags	object
Tag	array<object>	Tag list.
	object	Tag list.
Key	string	Tag key. Note Call the TagResources operation to create tags for the target cluster.	tag1
Value	string	Tag value.	test1
Category	string	Product series. This parameter is meaningful only for Data Warehouse Edition instances. Valid values: BASIC: Reserved-mode Basic Edition. CLUSTER: Reserved-mode Cluster Edition. MIXED_STORAGE: Elastic-mode Cluster Edition (new). Note For more information about product series, see product series.	MIXED_STORAGE
InnerPort	string	Internal network port of the cluster.	3306
VPCCloudInstanceId	string	Internal endpoint.	am-bp163885f8q21****-controller
InnerIp	string	Internal IP address of the cluster.	10.1.xx.xx
DtsJobId	string	DTS sync task ID. This parameter is returned only for MySQL analytic instances.	dtsb1578j90XXXX
ElasticIOResource	integer	Elastic IO Unit (EIU). For more information, see EIU details. Note This parameter is returned only for elastic-mode clusters.	2
RdsInstanceId	string	Source RDS instance ID for synchronization. This parameter is returned only for MySQL analytic instances.	rm-bp11q28kvl688****
ExecutorCount	string	Number of compute nodes used by the cluster in elastic mode.	1
DBNodeClass	string	Node specifications. This parameter is meaningful only for Data Warehouse Edition instances.	E8
DiskType	string	Disk type. Valid values: local_ssd: Local SSD. cloud: Basic disk. cloud_ssd: Standard SSD. cloud_efficiency: Ultra disk. cloud_essd: ESSD disk (PL1 level). cloud_essd2: ESSD disk (PL2 level). cloud_essd3: ESSD disk (PL3 level). Note For more information about ESSD disks, see ESSD disk specifications.	cloud_essd
DBNodeStorage	integer	Storage capacity of the cluster, in GB.	300
DBNodeCount	integer	Number of node groups.	2
TaskInfo	object	Task progress information.
Name	string	Task name.	analyticDBFlexibleScaleOut
Status	string	Task status. Valid values: NOT_RUN: Waiting to run. RUNNING: Running. SUCCEED: Completed.	RUNNING
Progress	string	Task progress, in percent (%).	10%
StepList	object
StepList	array<object>	Task steps.
	object	Task step.
StepName	string	Step name.	ApplyResource
StepDesc	string	Step description.	Apply resource
StepStatus	string	Step status. Valid values: NOT_RUN: Waiting to run. RUNNING: Running. SUCCEED: Completed.	SUCCEED
StepProgress	string	Step progress, in percent (%).	50%
StartTime	string	Start time of the step. Format: YYYY-MM-DDTHH:mm:ssZ.	2024-03-10T09:28:34Z
EndTime	string	End time of the step. Format: YYYY-MM-DDTHH:mm:ssZ.	2024-03-10T10:28:34Z
ProductForm	string	Product form. Valid values: LegacyForm: Traditional form. IntegrationForm: Integrated form.	IntegrationForm
ProductVersion	string	Product version. Valid values: BasicVersion: Basic Edition. EnterpriseVersion: Enterprise Edition.	EnterpriseVersion
ReservedNodeSize	string	Specification of each reserved resource node.	8ACU
ReservedNodeCount	integer	Number of reserved resource nodes.	1
AINodeSpec	string
AINodeNumber	integer

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": "",
        "AINodeNumber": 0
      }
    ]
  }
}

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.