Query clusters|V4.3.0| docs|Distributed Database

Query clusters

Last Updated：2024-09-18 09:05:55 Updated

Description

You can call this operation to query OceanBase clusters managed by OceanBase Cloud Platform (OCP).

You can query clusters based on conditions such as the keyword in cluster names and cluster status. If the OceanBase clusters are deployed in primary/standby mode, the returned result includes the primary and the standby clusters. You can determine the role of a cluster based on its attributes.

Call description

Prerequisite

You have the CLUSTER_VIEWER permissions.
You have passed the authentication for the OCP application service.

Request path

GET /api/v2/ob/clusters

Request parameters

Parameter	Type	Required	Example value	Description
page	Integer	No	1	The number of the page to return. The value starts from 1. Default value: 1.
size	Integer	No	10	The number of entries to return on each page. Default value: 10. Maximum value: 2000.
sort	String	No	name,asc	The rule for sorting the requested data.
name	String	No	foo	The keyword in the cluster name, which is case-insensitive.
status	StringArray	No	CREATING,RUNNING	The status of the cluster. Valid values: RUNNING CREATING DELETING STARTING RESTARTING STOPPING STOPPED TAKINGOVER MOVINGOUT SWITCHOVER FAILOVER OPERATING
withStandby	-	-	-	This parameter is deprecated and will be removed from later versions.

Response parameters

Parameter	Type	Description
data	Object	The data structure of ObCluster. For more information, see the following table.
├─ contents	Array	The array of the primary/standby cluster information. For more information about its data structure, see the following table.
├─ page	Object	The page information.
├─ totalElements	Integer	The total number of entries.
├─ totalPage	Integer	The total number of pages.
├─ number	Integer	The page number of the current page.
├─ size	Integer	The number of entries on the current page.
successful	Boolean	Indicates whether the request was successful.
timestamp	Datetime	The timestamp when the server completed the request.
duration	Integer	The amount of time taken by the server to process the request, in milliseconds.
status	Integer	The HTTP status code.
traceId	String	The trace ID of the request. This trace ID is used for troubleshooting.
server	String	The address of the application server that responded to the request.

Data structure of ObCluster

Parameter	Type	Description
primaryCluster	Object	The primary cluster of the current cluster.
standbyClusters	Array	The array of standby clusters of the current cluster.
id	Integer	The ID of the OceanBase cluster generated by the OCP system.
name	String	The name of the cluster.
obClusterId	Integer	The ID of the OceanBase cluster generated by the OceanBase Database system.
obVersion	String	The version of the cluster.
status	String	The status of the cluster. Valid values: RUNNING CREATING DELETING STARTING RESTARTING STOPPING STOPPED TAKINGOVER MOVINGOUT SWITCHOVER FAILOVER OPERATING
regionCount	Integer	The number of regions.
rootServers	Array	The information of Root Servers.
├─ address	String	The address of the Root Server, following the format of IP:Port.
├─ role	String	The role of the Root Server. Valid values: LEADER FOLLOWER
├─ sql_port	Integer	The SQL port number.
type	String	The type of the cluster. Valid values: PRIMARY STANDBY
regionCount	Integer	The number of regions.
tenantCount	Integer	The number of tenants.
partitionCount	Integer	The number of partitions.
serverCount	Integer	The number of OBServer nodes.
delayTime	Float	The delay of the standby cluster, in seconds.
syncStatus	String	The primary/standby cluster synchronization status. Valid values: VALID DISABLED SYNCHRONIZING
zones	Array	The list of zones.
createTime	DateTime	The creation time.
updateTime	DateTime	The update time.
creator	String	The creator of the cluster.
deadLockDetectionEnabled	Boolean	Indicates whether automatic deadlock detection is enabled.
failToQueryFromObReason	-	This parameter is deprecated and will be removed from later versions.

Data structure of zones

Parameter	Type	Description
name	String	The name of the zone.
idcName	String	The name of the IDC to which the zone belongs.
regionName	String	The region to which the zone belongs.
servers	Array	The list of servers.
clusterId	Long	The ID of the server.
obClusterId	Long	The ID of the OceanBase cluster generated by the OceanBase Database system.
serverCount	Integer	The number of servers.
hostCount	Integer	The number of hosts.

Examples

Sample request

Query the first page of cluster information, with 10 entries on each page.

GET /api/v2/ob/clusters?page=1&size=10

Sample response

{
    "data": {
        "contents": [
            {
                "createTime":" 2020-11-29T22:23:12+08:00",
                "creator":" admin",
                "id":1000002,
                "name":" test",
                "obClusterId":4,
                "obVersion":" 2.2.73",
                "regionCount":1,
                "rootServers": [
                    {
                        "address":" xxx.xxx.xxx.xxx:2882",
                        "role":" LEADER",
                        "sql_port":2881
                    }
                ],
                "serverCount":1,
                "standbyClusters": [

                ],
                "status":" RUNNING",
                "tenantCount":0,
                "type":" PRIMARY",
                "zones": [
                    {
                        "idcId":1,
                        "idcName":" hz",
                        "innerStatus":" ACTIVE",
                        "name":" zone1",
                        "operateStatus":" NORMAL",
                        "regionName":" hz",
                        "serverCount":1,
                        "servers": [

                        ],
                        "status":" RUNNING"
                    }
                ]
            }
        ],
        "page": {
            "number":1,
            "size":10,
            "totalElements":1,
            "totalPages":1
        }
    },
    "duration":108,
    "server": "a83ad33525",
    "status":200,
    "successful":true,
    "timestamp":" 2020-12-02T20:03:58.233+08:00",
    "traceId":" 3cfec9a5180748ff"
}