Query zones of an OceanBase cluster|V4.3.5| docs|Distributed Database

Query zones of an OceanBase cluster

Last Updated：2025-04-16 07:40:56 Updated

Description

You can call this operation to query zones of an OceanBase cluster.

Call description

Prerequisites

You have the permission to view the specified OceanBase cluster.

For more information about the permissions, see Overview.
You have passed the authentication for the OceanBase Cloud Platform (OCP) application service.

Request path

GET /api/v2/ob/clusters/{id}/zones

Path parameters

Parameter	Type	Required	Example value	Description
id	Integer	Yes	100	The ID of the OceanBase cluster for which you want to query the zones.

Response parameters

Basic data structure

Parameter	Type	Description
data	Object	The requested data.
├─ contents	Object	For more information, see Data structure of Zone.
├─ 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 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	Object	For more information, see Data structure of Server.
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.

Data structure of Server

Parameter	Type	Description
id	String	The ID of the OBServer node.
ip	String	The IP address of the OBServer node.
port	Integer	The port number.
sqlPort	Integer	The SQL port number.
runUser	String	The OS user.
runPath	String	The run path.
installPath	String	The installation path.
version	String	The version.
withRootserver	Boolean	Indicates whether RootService is deployed on the OBServer node.
status	String	The status.
innerStatus	Enum	The inner status of the OBServer node in OceanBase Database. Valid values: ACTIVE INACTIVE DELETING TAKEOVER_BY_RS
clusterId	Long	The ID of the cluster to which the OBServer node belongs.
zoneName	String	The name of the zone to which the OBServer node belongs.
regionName	String	The name of the region to which the OBServer node belongs.
idcName	String	The name of the IDC to which the OBServer node belongs.
hostId	Long	The ID of the host.
hostTypeName	String	The name of the host type.
hostStatus	Enum	The status of the host. Valid values: NEW ONLINE OFFLINE AGENT_RESTARTING AGENT_REINSTALLING SHUTDOWN DELETING AVAILABLE
startTime	DateTime	The start time.
stopTime	DateTime	The stop time.
arbitrationStatus	Enum	The connection status of the arbitration service. This parameter is supported in only OceanBase Database V4.2.0.0 and later. Valid values: ACTIVE INACTIVE
onlineCpuCoreRange	String	The CPU binding range of the OBServer node.

Examples

Sample request

Query zones of a cluster whose ID is 100.

GET /api/v2/ob/clusters/100/zones

Sample response

{
    "data": {
        "contents": [{
            "architecture": "x86_64",
            "clusterId": 1000014,
            "createTime": "2025-03-11T13:49:48+08:00",
            "hostCount": 1,
            "id": 1000042,
            "idcId": 1,
            "idcName": "adsd",
            "innerStatus": "ACTIVE",
            "name": "zone2",
            "obClusterId": 1658110665,
            "regionName": "OCP_META_REGION",
            "rootServer": {
                "address": "xxx.xxx.xxx.xxx:2882",
                "role": "FOLLOWER",
                "sql_port": 2891
            },
            "serverCount": 1,
            "servers": [{
                "arbitrationStatus": "ACTIVE",
                "clusterId": 1000014,
                "hostId": 1000007,
                "hostStatus": "ONLINE",
                "hostTypeName": "jixin",
                "id": 1000053,
                "idcName": "adsd",
                "innerStatus": "ACTIVE",
                "installPath": "/home/admin/oceanbase",
                "ip": "xxx.xxx.xxx.xxx",
                "onlineCpuCoreRange": "92-103",
                "port": 2882,
                "regionName": "OCP_META_REGION",
                "runPath": "/home/admin/oceanbase",
                "runUser": "admin",
                "sqlPort": 2891,
                "startTime": "2025-03-11T14:14:48+08:00",
                "status": "RUNNING",
                "stopTime": "1970-01-01T08:00:00+08:00",
                "updateTime": "2025-03-11T14:14:53+08:00",
                "version": "4.2.3.0_200000122024031116-a5db116b6dc6e002b318b57f413e64ec5aac804a(Mar 11 2024 16:25:08)",
                "withRootserver": false,
                "zoneName": "zone2"
            }],
            "status": "RUNNING",
            "updateTime": "2025-03-11T14:14:53+08:00"
        },
        {
            "architecture": "x86_64",
            "clusterId": 1000014,
            "createTime": "2025-03-11T13:49:48+08:00",
            "hostCount": 1,
            "id": 1000043,
            "idcId": 1,
            "idcName": "adsd",
            "innerStatus": "ACTIVE",
            "name": "zone3",
            "obClusterId": 1658110665,
            "regionName": "OCP_META_REGION",
            "rootServer": {
                "address": "xxx.xxx.xxx.xxx:2882",
                "role": "LEADER",
                "sql_port": 2891
            },
            "serverCount": 1,
            "servers": [{
                "arbitrationStatus": "ACTIVE",
                "clusterId": 1000014,
                "hostId": 1000004,
                "hostStatus": "ONLINE",
                "hostTypeName": "jixin",
                "id": 1000054,
                "idcName": "adsd",
                "innerStatus": "ACTIVE",
                "installPath": "/home/admin/oceanbase",
                "ip": "xxx.xxx.xxx.xxx",
                "onlineCpuCoreRange": "0-15",
                "port": 2882,
                "regionName": "OCP_META_REGION",
                "runPath": "/home/admin/oceanbase",
                "runUser": "admin",
                "sqlPort": 2891,
                "startTime": "2025-03-11T14:14:43+08:00",
                "status": "RUNNING",
                "stopTime": "1970-01-01T08:00:00+08:00",
                "updateTime": "2025-03-11T14:14:53+08:00",
                "version": "4.2.3.0_200000122024031116-a5db116b6dc6e002b318b57f413e64ec5aac804a(Mar 11 2024 16:25:08)",
                "withRootserver": true,
                "zoneName": "zone3"
            }],
            "status": "RUNNING",
            "updateTime": "2025-03-11T14:14:52+08:00"
        }]
    },
    "duration": 23,
    "server": "5e11a5f435",
    "status": 200,
    "successful": true,
    "timestamp": "2025-03-19T13:56:55.86+08:00",
    "traceId": "54110f0dedeefd95"
}