Help Center/ Data Warehouse Service/ API Reference/ API Description/ Cluster Management/ Querying Cluster Details
Updated on 2025-08-06 GMT+08:00
View PDF

Querying Cluster Details

Function

This API is used to query cluster details.

Calling Method

For details, see Calling APIs.

URI

GET /v1.0/{project_id}/clusters/{cluster_id}

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID. To obtain the value, see Obtaining a Project ID.

Constraints

N/A

Range

N/A

Default Value

N/A

cluster_id

Yes

String

Definition

Cluster ID. For details about how to obtain the value, see Obtaining the Cluster ID.

Constraints

The value must be a valid DWS cluster ID.

Range

It is a 36-digit UUID.

Default Value

N/A

Request Parameters

None

Response Parameters

Status code: 200

Table 2 Response body parameters

Parameter

Type

Description

cluster

ClusterDetail object

Definition

Cluster details.

Range

Non-null
Table 3 ClusterDetail

Parameter

Type

Description

id

String

Definition

Cluster ID.

Range

N/A

name

String

Definition

Cluster name.

Range

N/A

status

String

Definition

Cluster status.

Range

  • CREATING: The cluster is being created.

  • ACTIVE: The cluster is available.

  • FAILED: The cluster is unavailable.

  • CREATE_FAILED: The cluster failed to be created.

  • DELETING: The cluster is being deleted.

  • DELETE_FAILED: The cluster failed to be deleted.

  • DELETED: The cluster was deleted.

  • FROZEN: The cluster is frozen.

  • POLICE_FROZEN: The cluster is frozen by the public security.

version

String

Definition

Data warehouse version.

Range

N/A

updated

String

Definition

Last modification time of a cluster. The format is ISO8601:YYYY-MM-DDThh:mm:ssZ.

Range

N/A

created

String

Definition

Cluster creation time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Range

N/A

port

Integer

Definition

Cluster service port.

Range

8000 to 30000

endpoints

Array of Endpoints objects

Definition

Private network connection information about the cluster.

Range

Non-empty object array.

nodes

Array of Nodes objects

Definition

Cluster nodes.

Range

Non-empty object array.

tags

Array of Tags objects

Definition

Cluster tags.

Range

N/A

user_name

String

Definition

Administrator username.

Range

N/A

number_of_node

Integer

Definition

Number of nodes.

Range

N/A

recent_event

Integer

Definition

Number of events.

Range

N/A

availability_zone

String

Definition

AZ.

Range

N/A

enterprise_project_id

String

Definition

Enterprise project ID for a cluster. If this parameter is not specified, the default value 0 (indicating that the ID of the default enterprise project) is used.

Constraints

N/A

Range

N/A

Default Value

0

vpc_id

String

Definition

VPC ID.

Range

N/A

subnet_id

String

Definition

Subnet ID.

Range

N/A

public_ip

PublicIp object

Definition

Public IP address. If the parameter is not specified, public connection is not used by default.

Range

N/A

public_endpoints

Array of PublicEndpoints objects

Definition

Public IP address. If the parameter is not specified, public connection is not used by default.

Range

N/A

action_progress

Map<String,String>

Definition

Task information. It consists of a key and a value. The key indicates an ongoing task, and the value indicates the progress of the ongoing task.

Range

The key can contain but is not limited to the following values:

  • CREATING: The cluster is being created.

  • RESTORING

  • SNAPSHOTTING

  • GROWING

  • REBOOTING

  • SETTING_CONFIGURATION: Security settings are being configured.

  • CONFIGURING_EXT_DATASOURCE: The MRS connection is being configured.

  • ADD_CN_ING: A CN is being added.

  • DEL_CN_ING: A CN is being deleted.

  • REDISTRIBUTING: Redistribution is in progress.

  • ELB_BINDING: An ELB is being bound.

  • ELB_UNBINDING: An ELB is being unbound.

  • ELB_SWITCHING: An ELB is being switched.

  • NETWORK_CONFIGURING: The network is being configured.

  • DISK_EXPANDING: The disk is being expanded.

  • ACTIVE_STANDY_SWITCHOVER: The primary/standby switchover is being performed.

  • CLUSTER_SHRINKING: The cluster is being scaled in.

  • SHRINK_CHECKING: Cluster scale-in check is being performed.

  • FLAVOR_RESIZING: The flavor is being changed.

  • MANAGE_IP_BINDING: Login is being enabled.

  • FINE_GRAINED_RESTORING: The fine-grained restoration is in progress.

  • DR_RECOVERING: The DR recovery is in progress.

  • REPAIRING: The cluster is being repaired.

sub_status

String

Definition

Sub-status of the available clusters.

Range

  • NORMAL

  • READONLY

  • REDISTRIBUTING

  • REDISTRIBUTION-FAILURE

  • UNBALANCED

  • UNBALANCED | READONLY: unbalanced, read-only

  • DEGRADED

  • DEGRADED | READONLY

  • DEGRADED | UNBALANCED

  • UNBALANCED | REDISTRIBUTING

  • UNBALANCED | REDISTRIBUTION-FAILURE

  • READONLY | REDISTRIBUTION-FAILURE

  • UNBALANCED | READONLY | REDISTRIBUTION-FAILURE

  • DEGRADED | REDISTRIBUTION-FAILURE

  • DEGRADED | UNBALANCED | REDISTRIBUTION-FAILURE

  • DEGRADED | UNBALANCED | READONLY | REDISTRIBUTION-FAILURE

  • DEGRADED | UNBALANCED | READONLY

task_status

String

Definition

Task for cluster management.

Range

The value can contain but is not limited to the following values:

  • UNFREEZING

  • FREEZING

  • RESTORING

  • SNAPSHOTTING

  • GROWING

  • REBOOTING

  • SETTING_CONFIGURATION: Security settings are being configured.

  • CONFIGURING_EXT_DATASOURCE: The MRS connection is being configured.

  • DELETING_EXT_DATASOURCE: The MRS connection is being deleted.

  • REBOOT_FAILURE: The reboot failed.

  • RESIZE_FAILURE: The scale-out failed.

  • ADD_CN_ING: A CN is being added.

  • DEL_CN_ING: A CN is being deleted.

  • CREATING_NODE: A node is being added.

  • CREATE_NODE_FAILED: The node failed to be added.

  • DELETING_NODE: The node is being deleted.

  • DELETE_NODE_FAILED: The node failed to be deleted.

  • REDISTRIBUTING: Redistribution is in progress.

  • REDISTRIBUTE_FAILURE: Redistribution failed.

  • WAITING_REDISTRIBUTION: Redistribution is waiting.

  • REDISTRIBUTION_PAUSED: Redistribution is paused.

  • ELB_BINDING: An ELB is being bound.

  • ELB_BIND_FAILED: An ELB failed to be bound.

  • ELB_UNBINDING: An ELB is being unbound.

  • ELB_UNBIND_FAILED: An ELB failed to be unbound.

  • ELB_SWITCHING: An ELB is being switched.

  • ELB_SWITCHING_FAILED: An ELB failed to be switched.

  • NETWORK_CONFIGURING: The network is being configured.

  • NETWORK_CONFIG_FAILED: Network configuration failed.

  • DISK_EXPAND_FAILED: Disk capacity expansion failed.

  • DISK_EXPANDING: The disk is being expanded.

  • ACTIVE_STANDY_SWITCHOVER: The primary/standby switchover is being performed.

  • ACTIVE_STANDY_SWITCHOVER_FAILURE: The primary/standby switchover failed.

  • CLUSTER_SHRINK_FAILED: The cluster scale-in failed.

  • CLUSTER_SHRINKING: The cluster is being scaled in.

  • SHRINK_CHECK_FAILED: The cluster scale-in check failed.

  • SHRINK_CHECKING: Cluster scale-in check is being performed.

  • FLAVOR_RESIZING_FAILED: The flavor change failed.

  • FLAVOR_RESIZING: The flavor is being changed.

  • MANAGE_IP_BIND_FAILED: Login failed to be enabled.

  • MANAGE_IP_BINDING: Login is being enabled.

  • ORDER_PENDING: The order is pending to be paid.

  • FINE_GRAINED_RESTORING: The fine-grained restoration is in progress.

  • DR_RECOVERING: The DR recovery is in progress.

parameter_group

ParameterGroup object

Definition

Information about the parameter template associated with a cluster.

Range

N/A

node_type

String

Definition

Cluster flavors.

Range

N/A

node_type_id

String

Definition

Cluster flavor ID.

Range

N/A

security_group_id

String

Definition

Security group ID.

Range

N/A

order_id

String

Definition

Order ID, which is returned only when an instance is billed on a yearly/monthly basis. If this parameter is not left blank, the cluster is a yearly/monthly cluster.

Range

N/A

private_ip

Array of strings

Definition

Private IP addresses.

Range

N/A

maintain_window

MaintainWindow object

Definition

Cluster maintenance window.

Range

N/A

resize_info

ResizeInfo object

Definition

Cluster scale-out details.

Range

N/A

failed_reasons

FailedReason object

Definition

Failure cause. If the parameter is left blank, the cluster is in the normal state.

Range

N/A

elb

ElbResp object

Definition

ELB bound to the cluster.

Range

N/A
Table 4 Endpoints

Parameter

Type

Description

connect_info

String

Definition

Private network connection information.

Range

N/A

jdbc_url

String

Definition

JDBC URL of the private network.

Constraints

N/A

Range

N/A

Default Value

jdbc:postgresql://<connect_info>/<YOUR_DATABASE_NAME>
Table 5 Nodes

Parameter

Type

Description

id

String

Definition

Cluster instance ID.

Range

N/A

status

String

Definition

Cluster instance status.

Range

100: creating

199: idle

200: available

300: unavailable

303: creation failed

304: deleting

305: deletion failed

400: deleted

name

String

Definition

Instance name.

Range

N/A
Table 6 Tags

Parameter

Type

Description

key

String

Definition

Tag key.

Constraints

N/A

Range

  • It can contain a maximum of 128 Unicode characters. It cannot be an empty string, and cannot start or end with a space.

  • It cannot contain the following characters: =*<>\,|/

  • Only uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-) are allowed.

Default Value

N/A

value

String

Definition

Tag value.

Constraints

N/A

Range

  • The value can contain a maximum of 256 characters and can be an empty string. It cannot start or end with a space.

  • It cannot contain the following characters: =*<>\,|/

  • Only uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-) are allowed.

Default Value

N/A
Table 7 PublicIp

Parameter

Type

Description

public_bind_type

String

Definition

EIP binding type.

Constraints

N/A

Range

auto_assign

not_use

bind_existing

Default Value

null

eip_id

String

Definition

EIP ID.

Constraints

N/A

Range

N/A

Default Value

null
Table 8 PublicEndpoints

Parameter

Type

Description

public_connect_info

String

Definition

Public network connection information.

Range

N/A

jdbc_url

String

Definition

JDBC connection string of the public network.

Constraints

N/A

Range

N/A

Default Value

jdbc:postgresql://<public_connect_info>/<YOUR_DATABASE_name>
Table 9 ParameterGroup

Parameter

Type

Description

id

String

Definition

Parameter template ID.

Range

N/A

name

String

Definition

Parameter template name.

Range

N/A

status

String

Definition

Cluster parameter status.

Range

  • In-Sync

  • Applying

  • Pending-Reboot

  • Sync-Failure
Table 10 MaintainWindow

Parameter

Type

Description

day

String

Definition

Maintenance time in each week in the unit of day.

Range

  • Mon

  • Tue

  • Wed

  • Thu

  • Fri

  • Sat

  • Sun

start_time

String

Definition

Maintenance start time in HH:mm format. The time zone is GMT+0.

Range

N/A

end_time

String

Definition

Maintenance end time in HH:mm format. The time zone is GMT+0.

Range

N/A
Table 11 ResizeInfo

Parameter

Type

Description

target_node_num

Integer

Definition

Number of nodes after the scale-out.

Range

N/A

origin_node_num

Integer

Definition

Number of nodes before the scale-out.

Range

N/A

resize_status

String

Definition

Scale-out status.

Range

  • GROWING: The cluster is being scaled out.

  • RESIZE_FAILURE: The scale-out failed.

start_time

String

Definition

Scale-out start time. Format: ISO8601:YYYY-MM-DDThh:mm:ss.

Range

N/A
Table 12 FailedReason

Parameter

Type

Description

error_code

String

Definition

Error code.

Range

N/A

error_msg

String

Definition

Error message.

Range

N/A
Table 13 ElbResp

Parameter

Type

Description

public_ip

String

Definition

Public IP address.

Range

A valid public IPv4 address.

private_ip

String

Definition

Private IP address.

Range

A valid private IPv4 address.

private_endpoint

String

Definition

ELB endpoint address.

Range

N/A

name

String

Definition

ELB name.

Range

N/A

id

String

Definition

ELB ID.

Range

N/A

vpc_id

String

Definition

ID of the VPC that the ELB is associated with.

Range

N/A

Example Requests

Query cluster details.

GET https://{Endpoint}/v1.0/89cd04f168b84af6be287f71730fdb4b/clusters/b5c45780-1006-49e3-b2d5-b3229975bbc7

Example Responses

Status code: 200

Cluster details queried.

{
  "cluster" : {
    "id" : "7d85f602-a948-4a30-afd4-e84f47471c15",
    "name" : "dws-1",
    "status" : "AVAILABLE",
    "version" : "1.2.0",
    "updated" : "2018-02-10T14:28:14Z",
    "created" : "2018-02-10T14:28:14Z",
    "port" : 8000,
    "endpoints" : [ {
      "connect_info" : "dws-1.cn-north-4.dwscloud.com",
      "jdbc_url" : "jdbc:postgresql://dws-1.cn-north-4.dwscloud.com/<YOUR_DATABASE_name>"
    } ],
    "nodes" : [ {
      "id" : "acaf62a4-41b3-4106-bf6b-2f669d88291e",
      "name" : "dws-1-dws-cn-cn-1-1",
      "status" : "200"
    }, {
      "id" : "d32de51e-4fcd-4e5a-a9dc-bb903abb494b",
      "name" : "dws-1-dws-cn-cn-2-1",
      "status" : "200"
    }, {
      "id" : "d71a4a25-c9bc-4ffd-9f4a-e422aef327f9",
      "name" : "dws-1-dws-cn-cn-3-1",
      "status" : "200"
    } ],
    "tags" : [ {
      "key" : "key1",
      "value" : "value1"
    }, {
      "key" : "key2",
      "value" : "value2"
    } ],
    "user_name" : "dbadmin",
    "number_of_node" : 3,
    "recent_event" : 6,
    "availability_zone" : "cn-north-4b",
    "enterprise_project_id" : "0",
    "node_type" : "dws.m1.xlarge.ultrahigh",
    "vpc_id" : "85b20d7e-9eb7-4b2a-98f3-3c8843ea3574",
    "subnet_id" : "374eca02-cfc4-4de7-8ab5-dbebf7d9a720",
    "public_ip" : {
      "public_bind_type" : "auto_assign",
      "eip_id" : "85b20d7e-9etypeb2a-98f3-3c8843ea3574"
    },
    "public_endpoints" : [ {
      "public_connect_info" : "dws-1.cn-north-4.dwscloud.com",
      "jdbc_url" : "jdbc:postgresql://dws-1.cn-north-4.dwscloud.com/<YOUR_DATABASE_name>"
    } ],
    "action_progress" : {
      "SNAPSHOTTING" : "20%"
    },
    "sub_status" : "READONLY",
    "task_status" : "SNAPSHOTTING",
    "parameter_group" : {
      "id" : "157e9cc4-64a8-11e8-adc0-fa7ae01bbebc",
      "name" : "Default-Parameter-Group-dws ",
      "status" : "In-Sync"
    },
    "security_group_id" : "dc3ec145-9029-4b39-b5a3-ace5a01f772b",
    "order_id" : "",
    "private_ip" : [ "192.168.0.12", "192.168.0.66" ],
    "maintain_window" : {
      "day" : "Wed",
      "start_time" : "22:00",
      "end_time" : "02:00"
    },
    "resize_info" : {
      "target_node_num" : "6",
      "origin_node_num" : "3",
      "resize_status" : "GROWING",
      "start_time" : "2018-02-14T14:28:14Z"
    }
  }
}

Status Codes

Status Code

Description

200

Cluster details queried.

400

Request error.

401

Authentication failed.

403

You do not have required permissions.

404

No resources found.

500

Internal server error.

503

Service unavailable.
Parent Topic: Cluster Management