Query OceanBase clusters|V4.3.5| docs|Distributed Database

Query OceanBase clusters

Last Updated：2025-04-16 07:40:56 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

Prerequisites

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 records 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
withRemote	Enum	No	NONE	Specifies whether to query OceanBase clusters managed by remote OCP clusters. This parameter takes effect only if you have deployed OCP in multi-cluster mode. Valid values: NONE: Query none of them. ALL: Query all of them. RELATED: Query local tenants and the remote tenants that are in a primary/standby relationship with local tenants.
foldStandby	-	-	-	This parameter is deprecated and will be removed from later versions.

Response parameters

Basic data structure

Parameter	Type	Description
data	Object	For more information, see Data structure of ObCluster.
├─ contents	Array	The array of the primary/standby cluster information.
├─ page	Object	The pagination information.
├─ totalElements	Integer	The total number of records.
├─ totalPage	Integer	The total number of pages.
├─ number	Integer	The page number of the current page.
├─ size	Integer	The number of records 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 cluster.
name	String	The name of the cluster.
vpcId	Integer	The ID of the virtual private cloud (VPC) to which the cluster belongs.
vpcName	String	The name of the VPC to which the cluster belongs.
obClusterId	Integer	The ID of the cluster in OceanBase Database.
obVersion	String	The version of the cluster.
minObBuildVersion	String	The minimum build version in the OceanBase cluster. The build versions of servers in the cluster may be different, and the value of this parameter is the minimum one.
status	String	The status of the cluster. Valid values: RUNNING CREATING DELETING STARTING RESTARTING STOPPING STOPPED TAKINGOVER MOVINGOUT SWITCHOVER FAILOVER OPERATING
origin	Enum	The type of the cluster. Valid values: CREATED: The OceanBase cluster was created by the current OCP. TAKEN_OVER: The OceanBase cluster was taken over to the current OCP.
compactionStatus	Enum	The major compaction status. Valid values: IDLE: The major compaction has not started. MERGING: The major compaction is in progress. INDEXING: The newly compacted data is being indexed. The INDEX state is no longer used in OceanBase Database V2.2 and later. ERROR: An error occurred. TIMEOUT: The major compaction timed out. MOST_MERGED: The major compaction is complete.
rpmName	String	The name of the RPM package.
architecture	String	The hardware architecture.
obproxyClusters	Array	The information about OBProxy clusters.
rootServers	Array	The information about RootServers.
├─ address	String	The address of the RootServer in the format of `IP:Port`.
├─ role	String	The role of the RootServer. 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.
consistentTime	String	The point in time when the standby cluster was synchronized with the primary cluster.
protectionMode	Enum	The cluster protection mode. Valid values: MAXIMUM_PERFORMANCE MAXIMUM_PROTECTION MAXIMUM_AVAILABILITY UNKNOWN
redoTransportMode	Enum	The log transfer mode of the cluster. Valid values: SYNC: indicates synchronous log transfer. ASYNC: indicates asynchronous log transfer. UNKNOWN: indicates an unknown mode.
redoTransportStatus	Enum	The actual log transfer status of the cluster.
syncStatus	String	The primary/standby synchronization status. Valid values: VALID: The synchronization is complete. DISABLED: The synchronization is disabled. SYNCHRONIZING: The synchronization is in progress.
syncInfo	String	The description for the primary/standby synchronization status.
zoneTopo	String	The zone deployment topology.
configUrl	String	The ConfigUrl of the cluster.
startupParameters	Array	The startup parameters of the cluster.
attributes	Object	The attributes of the cluster.
├─InstallPath	String	The installation path of the cluster.
├─RunPath	String	The run path.
├─DataDiskPath	String	The data disk path.
├─LogDiskPath	String	The log disk path.
├─DiskPathStyle	Enum	OBD DEFAULT
├─OperatingSystemUser	String	The username of the OS user of the host.
├─SqlPort	Integer	The SQL port number.
├─SvrPort	Integer	The RPC port number.
availableOperations	Array	The operations that can be executed.
zones	Object	For more information, see Data structure of Zone.
tenants	Array	The list of tenants.
createTime	DateTime	The time when the cluster was created.
updateTime	DateTime	The time when the cluster was last updated.
creator	String	The username of the user that created the cluster.
alarmSummaries	-	This parameter is deprecated and will be removed from later versions.
resourceStats	-	This parameter is deprecated and will be removed from later versions.
performanceStats	-	This parameter is deprecated and will be removed from later versions.
failToQueryFromObReason	-	This parameter is deprecated and will be removed from later versions.
ocpCluster	Object	The information about the OCP cluster.
├─ id	Long	The ID of the OCP cluster.
├─ name	String	The name of the OCP cluster.
├─ role	Enum	The role of the OCP cluster. Valid values: LEADER: indicates the primary OCP cluster. CANDIDATE: indicates the candidate primary OCP cluster. FOLLOWER: indicates a standby OCP cluster.
├─ address	String	The address of the OCP cluster.
├─ version	String	The version of OCP.
├─ status	Enum	The status of the OCP cluster. Valid values: NORMAL: The OCP cluster is running. UPGRADING: The OCP cluster is being upgraded. SWITCHING: The OCP cluster is in the progress of a failover or switchover. OFFLINE: The OCP cluster is unavailable. When the primary OCP cluster detects a heartbeat timeout from a standby OCP cluster, it sets the standby cluster to the `OFFLINE` state. ABANDONED: The original primary OCP cluster was abandoned after a failover.
├─ lastHeartbeatTime	DateTime	The timestamp of the last heartbeat.
deadLockDetectionEnabled	Boolean	Indicates whether automatic deadlock detection is enabled.
cgroupEnabled	Boolean	Indicates whether the cgroup feature is enabled for the cluster.
enableCgroup	Boolean	Indicates whether the cgroup feature has been successfully enabled for the cluster.
oversellingFactor	Integer	The resource overprovisioning factor. Valid values: [100, 200], indicating that the factor ranges from 100% to 200%. Default value: 100, indicating that resources are not overprovisioned.
originalPrimary	Boolean	Indicates whether the cluster was the primary cluster before the failover.
arbitrationServiceInfo	Object	The information about the arbitration service.
arbitrationServiceGroup	Object	The information about the arbitration service group.
obArbitrationStatus	Enum	The communication status between OceanBase Database and the arbitration service. Valid values: ACTIVE INACTIVE
tags	Array	The tags for the cluster.
packageOperatingSystem	String	The operating system of the software package.
loadType	Enum	The type of the load. Valid values: EXPRESS_OLTP COMPLEX_OLTP HTAP OLAP KV
obStartTime	DateTime	The start time of the cluster.

Data structure of Zone

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 cluster.
obClusterId	Long	The ID of the cluster in OceanBase Database.
serverCount	Integer	The number of servers.
hostCount	Integer	The number of hosts.
architecture	String	The CPU architecture.
status	Enum	The status of the zone. Valid values: RUNNING UNAVAILABLE SERVICE_STOPPED STOPPED DELETED CREATING (an intermediate O&M state) STOPPING (an intermediate O&M state) STARTING (an intermediate O&M state) RESTARTING (an intermediate O&M state) DELETING (an intermediate O&M state) OPERATING (an intermediate O&M state)
innerStatus	Enum	The inner status of the zone in OceanBase Database, which is the value in the `status` column of the `__all_server` table. Valid values: ACTIVE INACTIVE
compactionStatus	Enum	The major compaction status. Valid values: IDLE: The major compaction has not started. MERGING: The major compaction is in progress. INDEXING: The newly compacted data is being indexed. The INDEX state is no longer used in OceanBase Database V2.2 and later. ERROR: An error occurred. TIMEOUT: The major compaction timed out. MOST_MERGED: The major compaction is complete.
rootServer	Object	The RootServer of the zone.
availableOperations	Object	The operations that can be executed.

Examples

Sample request

Query OceanBase clusters and return only the first page, with a page size of 10.

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

Sample response

{
    "data": {
        "contents": [
            {
                "id": 1,
                "name": "ExampleCluster",
                "vpcId": 1001,
                "vpcName": "example-vpc",
                "obClusterId": 2001,
                "obVersion": "4.2.0.0_100000132023071110",
                "minObBuildVersion": "4.2.0.0",
                "status": "RUNNING",
                "origin": "CREATED",
                "operatingTaskInstanceId": 3001,
                "statusAnalysis": {
                    "startTime": "2023-10-01T10:15:30Z",
                    "reason": "Normal operation",
                    "action": "No action needed",
                    "reasonType": "Healthy",
                    "diagnosisType": "None",
                    "diagnosisContent": {}
                },
                "compactionStatus": "IDLE",
                "rpmName": "oceanbase-4.2.0.rpm",
                "architecture": "x86_64",
                "type": "PRIMARY",
                "obproxyClusters": [
                    {
                        "id": 4001,
                        "name": "ObproxyCluster1",
                        "vpcId": 1001,
                        "vpcName": "example-vpc",
                        "parameterVersion": 1,
                        "creatorId": 5001,
                        "creatorName": "admin",
                        "clusterStatus": "RUNNING",
                        "operatingTaskInstanceId": 6001,
                        "statusAnalysis": {
                            "startTime": "2023-10-01T10:15:30Z",
                            "reason": "Normal operation",
                            "action": "No action needed",
                            "reasonType": "Healthy",
                            "diagnosisType": "None",
                            "diagnosisContent": {}
                        },
                        "createTime": "2023-10-01T10:00:00Z",
                        "updateTime": "2023-10-01T10:15:30Z",
                        "configUrl": "http://example.com/config",
                        "address": "xxx.xxx.xxx.xxx",
                        "port": 8888,
                        "workMode": "RS_LIST",
                        "obLinks": []
                    }
                ],
                "regionCount": 1,
                "tenantCount": 5,
                "partitionCount": 10,
                "serverCount": 3,
                "consistentTime": "2023-10-01T10:15:30Z",
                "delayTime": 0.5,
                "protectionMode": "MAXIMUM_PERFORMANCE",
                "redoTransportMode": "SYNC",
                "syncStatus": "VALID",
                "syncInfo": "No sync issues",
                "zoneTopo": "zone1->zone2",
                "configUrl": "http://example.com/cluster_config",
                "startupParameters": {},
                "attributes": {
                    "InstallPath": "/home/admin/oceanbase",
                    "RunPath": "/home/admin/oceanbase/run",
                    "DataDiskPath": "/data/1",
                    "LogDiskPath": "/logs",
                    "DiskPathStyle": "OBD",
                    "OperatingSystemUser": "admin",
                    "SqlPort": 3306,
                    "SvrPort": 5000
                },
                "zones": [
                    {
                        "id": 7001,
                        "name": "ZoneA",
                        "idcId": 8001,
                        "idcName": "IDC1",
                        "regionName": "Region1",
                        "architecture": "x86_64",
                        "servers": [{
                            "id": 9001,
                            "ip": "xxx.xxx.xxx.xxx",
                            "port": 3306,
                            "sqlPort": 3306,
                            "runUser": "admin",
                            "runPath": "/home/admin/rs",
                            "installPath": "/data/1",
                            "version": "4.2.0.0",
                            "withRootserver": true,
                            "status": "RUNNING",
                            "innerStatus": "ACTIVE",
                            "operatingTaskInstanceId": 10001,
                            "statusAnalysis": {
                                "startTime": "2023-10-01T10:00:00Z",
                                "reason": "Normal operation",
                                "action": "No action needed",
                                "reasonType": "Healthy",
                                "diagnosisType": "None",
                                "diagnosisContent": {}
                            },
                            "updateTime": "2023-10-01T10:15:30Z",
                            "clusterId": 2001,
                            "zoneName": "ZoneA",
                            "regionName": "Region1",
                            "idcName": "IDC1",
                            "hostId": 3001,
                            "hostTypeName": "Default",
                            "hostStatus": "ONLINE",
                            "startTime": "2023-10-01T09:00:00Z",
                            "stopTime": null
                        }],
                        "status": "RUNNING",
                        "operatingTaskInstanceId": 11001,
                        "statusAnalysis": {
                            "startTime": "2023-10-01T10:00:00Z",
                            "reason": "Normal operation",
                            "action": "No action needed",
                            "reasonType": "Healthy",
                            "diagnosisType": "None",
                            "diagnosisContent": {}
                        },
                        "innerStatus": "ACTIVE",
                        "compactionStatus": "IDLE",
                        "clusterId": 2001,
                        "obClusterId": 2001,
                        "serverCount": 1,
                        "hostCount": 1,
                        "createTime": "2023-10-01T09:00:00Z",
                        "updateTime": "2023-10-01T10:15:30Z"
                    }
                ],
                "createTime": "2023-10-01T10:00:00Z",
                "updateTime": "2023-10-01T10:15:30Z",
                "creator": "admin"
            }
        ],
        "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"
}