Help Center/ GaussDB/ API Reference/ APIs (Recommended)/ Instance Management/ Querying the Components of a DB Instance
Updated on 2025-08-19 GMT+08:00

Querying the Components of a DB Instance

Function

This API is used to query components of a DB instance. Before calling this API:

URI

GET /v3/{project_id}/instances/{instance_id}/components
Table 1 Parameter description

Name

Type

Mandatory

Description

project_id

String

Yes

Definition

Project ID of a tenant in a region.

To obtain the value, see Obtaining a Project ID.

Constraints

N/A

Range

The value can contain 32 characters. Only letters and digits are allowed.

Default Value

N/A

instance_id

String

Yes

Definition

Instance ID, which uniquely identifies an instance.

Constraints

N/A

Range

The value can contain 36 characters. Only letters and digits are allowed.

Default Value

N/A

limit

Integer

No

Definition

Number of records returned by a query. For example, if this parameter is set to 10, a maximum of 10 records can be displayed.

Constraints

N/A

Range

1–100

Default Value

100

offset

Integer

No

Definition

Index offset. The query starts from the next piece of data indexed by this parameter. For example, if this parameter is set to 0 and limit is set to 10, only the 1st to 10th data records are displayed.

Constraints

The value must be a non-negative integer.

Range

1–100

Default Value

0: The query starts from the first data record.

component_type

String

No

Definition

Component type, which is used to filter the component information of the required component type. If the parameter is transferred, the corresponding component information is queried.

Constraints

N/A

Range

  • ALL: All component types are queried.
  • CN: The CN component type is queried.
  • DN: The DN component type is queried.
  • CM: The CMS component type is queried.
  • GTM: The GTM component type is queried.
  • ETCD: The ETCD component type is queried.

Default Value

ALL

availability_zone_id

String

No

Definition

ID of the AZ where the primary component is located. The default value is ALL, indicating that component information of nodes in all AZs of the instance is queried. When you query the AZ where a primary DN is located, the information of all DNs in the same shard as the primary DN is displayed. When you query the AZ where a CN is located, only the CN information in the AZ is displayed. When you query the AZ where a component (except CNs or DNs) is located, information about all components of the same type is returned. If there is no such a component, no information is returned.

Constraints

N/A

Range

N/A

Default Value

Request Parameters

None

Response Parameters

Table 2 Parameter description

Name

Type

Description

nodes

Array of objects

Definition

Component details.

For details, see Table 3.

total_count

Integer

Definition

Total number of records.

Range

N/A

Table 3 nodes description

Name

Type

Description

id

String

Definition

Node ID.

Range

N/A

components

Array of objects

Component information under the instance node. For details, see Table 4.

name

String

Definition

Node name.

Range

N/A

availability_zone_id

String

Definition

Code of the AZ where the node is located.

Range

N/A

description

String

Definition

AZ description.

Range

N/A

status

String

Definition

Node status.

Range

N/A

Table 4 components description

Name

Type

Description

id

String

Definition

Component ID.

Range

  • Global Transaction Manager (GTM): manages the status of transactions.
  • Cluster Management Server (CMS): manages the instance status.
  • Data node (DN): stores and queries table data.
  • Coordinator node (CN): stores database metadata, distributes and executes query tasks, and then returns the query results from DNs to applications.
  • Editable Text Configuration Daemon (ETCD): serves as a distributed key-value storage system used for configuration sharing and service discovery (registration and search).

role

String

Definition

Node role.

Range

  • master: primary node
  • slave: standby node

status

String

Definition

Component status.

Range

  • Primary: primary component
  • Normal: The component is normal.
  • Down: The component is abnormal.
  • Standby: standby component
  • StateFollower: standby ETCD
  • StateLeader: primary ETCD
  • StateCandidate: arbitration ETCD

distributed_id

String

Definition

Group ID. This parameter is used to identify DNs in the same shard. For other components, the value is an empty string.

Range

N/A

type

String

Definition

Node type.

Range

  • DN: DN type
  • CN: CN type
  • GTM: GTM type
  • CM: CMS type
  • ETCD: ETCD type

detail

String

Definition

Details.

Range

N/A

Example Request

Querying the components of a DB instance

GET https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e663/instances/dd93e98e103b4fc4b5a978a6bd6f03a9in14/components

Example Response

Components of the centralized instance queried.
{
    "nodes": [
        {
            "components": [
                {
                    "id": "cm_1",
                    "role": "master",
                    "status": "Primary",
                    "distributed_id": "",
                    "type" : "CM", 
                    "detail" : "" 
                },
                {
                    "id": "etcd_7001",
                    "role": "master",
                    "status": "StateLeader",
                    "distributed_id": "",
                    "type" : "ETCD", 
                    "detail" : "" 
                },
                {
                    "id": "dn_6001",
                    "role": "master",
                    "status": "Primary",
                    "distributed_id": "60011",
                    "type" : "DN", 
                    "detail" : "Normal" 
                }
            ],
            "id": "7d19f72f8f514564bd92962a6fbddb7dno14",
            "name": "gauss-9e1a_root_0",
            "availability_zone_id": "cn-southwest-244a",
            "description": "az1",
            "status": "normal"
        },
        {
            "components": [
                {
                    "id": "cm_3",
                    "role": "slave",
                    "status": "Standby",
                    "distributed_id": "",
                    "type" : "CM", 
                    "detail" : "" 
                },
                {
                    "id": "etcd_7003",
                    "role": "slave",
                    "status": "StateFollower",
                    "distributed_id": "",
                    "type" : "ETCD", 
                    "detail" : "" 
                },
                {
                    "id": "dn_6003",
                    "role": "slave",
                    "status": "Standby",
                    "distributed_id": "60011",
                    "type" : "DN", 
                    "detail" : "Normal" 
                }
            ],
            "id": "aafc2e14234d4c9eadb481fb0a09a865no14",
            "name": "gauss-9e1a_root_2",
            "availability_zone_id": "cn-southwest-244a",
            "description": "az1",
            "status": "normal"
        },
        {
            "components": [
                {
                    "id": "cm_2",
                    "role": "slave",
                    "status": "Standby",
                    "distributed_id": "",
                    "type" : "CM", 
                    "detail" : "" 
                },
                {
                    "id": "etcd_7002",
                    "role": "slave",
                    "status": "StateFollower",
                    "distributed_id": "",
                    "type" : "ETCD", 
                    "detail" : "" 
                },
                {
                    "id": "dn_6002",
                    "role": "slave",
                    "status": "Standby",
                    "distributed_id": "60011",
                    "type" : "DN", 
                    "detail" : "Normal" 
                }
            ],
            "id": "d6c6c6e6b48c41d79d99d7240751d744no14",
            "name": "gauss-9e1a_root_1",
            "availability_zone_id": "cn-southwest-244a",
            "description": "az1",
            "status": "normal"
        }
    ],
    "total_count": 3
}
Components of the distributed instance in the independent deployment queried.
{
    "nodes": [
        {
            "components": [
                {
                    "id": "cn_5001",
                    "role": "master",
                    "status": "Normal",
                    "distributed_id": "",
                    "type": "CN",
                    "detail": ""
                }
            ],
            "id": "e0c39a9b9e91421cacbfbf75c47e0c9dno14",
            "name": "gauss-6b36_gaussdbv5cn_0",
            "hostname": null,
            "availability_zone_id": "cn-southwest-244a",
            "description": "az1",
            "status": "normal"
        },
        {
            "components": [
                {
                    "id": "gtm_1002",
                    "role": "slave",
                    "status": "Standby",
                    "distributed_id": "",
                    "type": "GTM",
                    "detail": "Connection ok"
                }
            ],
            "id": "a19a1844ab93407489d8a63ca298f908no14",
            "name": "gauss-6b36_gaussdbv5gtm_0",
            "hostname": null,
            "availability_zone_id": "cn-southwest-244a",
            "description": "az1",
            "status": "normal"
        },
        {
            "components": [
                {
                    "id": "gtm_1003",
                    "role": "slave",
                    "status": "Standby",
                    "distributed_id": "",
                    "type": "GTM",
                    "detail": "Connection ok"
                }
            ],
            "id": "fd949ad6b00c4d72b7af5f015817d4d9no14",
            "name": "gauss-6b36_gaussdbv5gtm_1",
            "hostname": null,
            "availability_zone_id": "cn-southwest-244b",
            "description": "az2",
            "status": "normal"
        },
        {
            "components": [
                {
                    "id": "cm_2",
                    "role": "slave",
                    "status": "Standby",
                    "distributed_id": "",
                    "type": "CM",
                    "detail": ""
                },
                {
                    "id": "etcd_7002",
                    "role": "slave",
                    "status": "StateFollower",
                    "distributed_id": "",
                    "type": "ETCD",
                    "detail": ""
                }
            ],
            "id": "ac7e24fc9626479c96ab6215f2107faeno14",
            "name": "gauss-6b36_gaussdbv5cms_1",
            "hostname": null,
            "availability_zone_id": "cn-southwest-244b",
            "description": "az2",
            "status": "normal"
        },
        {
            "components": [
                {
                    "id": "dn_6001",
                    "role": "master",
                    "status": "Primary",
                    "distributed_id": "60011",
                    "type": "DN",
                    "detail": "Normal"
                }
            ],
            "id": "0989068696f94631a45b3f2b13ac7810no14",
            "name": "gauss-6b36_gaussdbv5dn1_0",
            "hostname": null,
            "availability_zone_id": "cn-southwest-244a",
            "description": "az1",
            "status": "normal"
        },
        {
            "components": [
                {
                    "id": "cm_1",
                    "role": "master",
                    "status": "Primary",
                    "distributed_id": "",
                    "type": "CM",
                    "detail": ""
                },
                {
                    "id": "etcd_7001",
                    "role": "master",
                    "status": "StateFollower",
                    "distributed_id": "",
                    "type": "ETCD",
                    "detail": ""
                }
            ],
            "id": "912ca1f9f12f41968d60d82a7f630bedno14",
            "name": "gauss-6b36_gaussdbv5cms_2",
            "hostname": null,
            "availability_zone_id": "cn-southwest-244c",
            "description": "az3",
            "status": "normal"
        },
        {
            "components": [
                {
                    "id": "dn_6002",
                    "role": "slave",
                    "status": "Standby",
                    "distributed_id": "60011",
                    "type": "DN",
                    "detail": "Normal"
                }
            ],
            "id": "365261e60ac14dff846480e8cc555d66no14",
            "name": "gauss-6b36_gaussdbv5dn1_1",
            "hostname": null,
            "availability_zone_id": "cn-southwest-244b",
            "description": "az2",
            "status": "normal"
        },
        {
            "components": [
                {
                    "id": "dn_6003",
                    "role": "slave",
                    "status": "Standby",
                    "distributed_id": "60011",
                    "type": "DN",
                    "detail": "Normal"
                }
            ],
            "id": "3ce7e13a25524e7b81d78cad9afd9464no14",
            "name": "gauss-6b36_gaussdbv5dn1_2",
            "hostname": null,
            "availability_zone_id": "cn-southwest-244c",
            "description": "az3",
            "status": "normal"
        },
        {
            "components": [
                {
                    "id": "cm_3",
                    "role": "slave",
                    "status": "Standby",
                    "distributed_id": "",
                    "type": "CM",
                    "detail": ""
                },
                {
                    "id": "etcd_7003",
                    "role": "slave",
                    "status": "StateLeader",
                    "distributed_id": "",
                    "type": "ETCD",
                    "detail": ""
                }
            ],
            "id": "e0deb77337604d149a76ce02b5060d86no14",
            "name": "gauss-6b36_gaussdbv5cms_0",
            "hostname": null,
            "availability_zone_id": "cn-southwest-244a",
            "description": "az1",
            "status": "normal"
        },
        {
            "components": [
                {
                    "id": "gtm_1001",
                    "role": "master",
                    "status": "Primary",
                    "distributed_id": "",
                    "type": "GTM",
                    "detail": "Connection ok"
                }
            ],
            "id": "9a88dc2a3f3e4f8c844f86dc032fde84no14",
            "name": "gauss-6b36_gaussdbv5gtm_2",
            "hostname": null,
            "availability_zone_id": "cn-southwest-244c",
            "description": "az3",
            "status": "normal"
        }
    ],
    "total_count": 10
}

Status Codes

Error Codes

For details, see Error Codes.