Query all tenants|V4.3.5| docs|Distributed Database

Query all tenants

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

Description

You can call this operation to query all tenants.

Call description

Prerequisites

You have passed the authentication for the OceanBase Cloud Platform (OCP) application service.
Only the tenants in the clusters that you have the read permission are returned.

Request path

GET /api/v2/ob/tenants

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 names of the tenants to query, which is case-insensitive.
mode	StringArray	No	ORACLE	The mode of the tenants to query. Valid values: ORACLE MYSQL
locked	Boolean	No	false	Specifies whether to query only locked tenants. Valid values: If you do not specify this parameter, all tenants are queried. If you set the value to `true`, only locked tenants are queried. If you set the value to `false`, only unlocked tenants are queried.
clusterName	String	No	cluster1	The name of the cluster.
readonly	Boolean	No	false	Specifies whether to query only tenants in the read-only state. Valid values: If you do not specify this parameter, all tenants are queried. If you set the value to `true`, only tenants in the read-only state are queried. If you set the value to `false`, only tenants not in the read-only state are queried.
status	StringArray	No	NORMAL	The status of the tenants to query. Valid values: NORMAL CREATING MODIFYING DELETING
withRemote	Enum	No	NONE	Specifies whether to query OceanBase Database tenants 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.
tagId	Array	No	-	The IDs of the tags.

Response parameters

Basic data structure

Parameter	Type	Description
data	Object	The requested business data.
├─ contents	Array	For more information, see Data structure of tenant 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 server that responds to the request.

Data structure of tenant information

Parameter	Type	Description
id	Integer	The ID of the tenant.
name	String	The name of the tenant.
clusterName	String	The name of the cluster to which the tenant belongs.
clusterId	Integer	The ID of the cluster to which the tenant belongs.
obClusterId	Integer	The ID of the cluster to which the tenant belongs in OceanBase Database.
arbitrationServiceId	Long	The ID of the arbitration service.
clusterType	String	The type of the cluster to which the tenant belongs. Valid values: PRIMARY STANDBY
clusterStatus	Enum	The status of the cluster. Valid values: RUNNING UNAVAILABLE STOPPED CREATING TAKINGOVER DELETING MOVINGOUT RESTARTING STARTING STOPPING SWITCHOVER FAILOVER UPGRADING OPERATING ABANDONED DISCONNECTING STARTING_IN_READ_ONLY MOVED_OUT
syncStatus	Enum	The primary/standby synchronization status. Valid values: VALID: The synchronization is complete. DISABLED: The synchronization is disabled. DISABLED_WITH_READ_ONLY: Data can be read only. SYNCHRONIZING: The synchronization is in progress. This status value is unavailable in the OceanBase Database system. UNKNOWN: The status is unknown.
mode	String	The mode of the tenant. Valid values: ORACLE MYSQL
createTime	Datetime	The time when the tenant was created.
primaryZone	String	The primary zone of the tenant.
zoneList	String	The zones of the tenant.
locality	String	The replica distribution of the tenant.
status	String	The status of the tenant. Valid values: NORMAL CREATING MODIFYING DELETING
locked	Boolean	Indicates whether the tenant is locked.
readonly	Boolean	Indicates whether the tenant is read-only.
obVersion	String	The version of the OceanBase cluster to which the tenant belongs.
description	String	The description of the tenant.
obTenantId	Long	The ID of the tenant in OceanBase Database. The value may be empty if the tenant is being created.
sqlAuditEnabled	Boolean	The value of the `ob_enable_sql_audit` parameter, which indicates whether SQL auditing is enabled for the tenant.
arbitrationStatus	Enum	The status of the arbitration service. Valid values: ENABLED ENABLING DISABLED DISABLING
role	Enum	The role of the tenant. Valid values: PRIMARY: The tenant is the primary tenant. STANDBY: The tenant is a standby tenant. CLONE: The tenant is a cloned tenant. RESTORE: The tenant is being restored. The value automatically changes to `STANDBY` after the tenant is restored. UNKNOWN: The role of the tenant is unknown.
serviceNameInfo	Object	The service name information of the tenant.
├─serviceName	String	The service name of the tenant.
├─serviceNameStatus	Enum	The status of the service name of the tenant. Valid values: VALID INVALID
├─conflictTenant	Object	The tenant that has the same service name as the current tenant.
logTransportMode	Enum	The mode of log transfer between the primary tenant and standby tenants. Valid values: NETWORK LOG_BACKUP
ocpClusterView	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	4.3.5-SNAPSHOT	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.
basicPrimaryTenant	Object	The information about the primary tenant of the current tenant.
├─tenantId	Long	The primary key ID of the tenant in OCP.
├─obTenantId	Long	The ID of the tenant in OceanBase Database.
├─tenantName	String	The name of the tenant.
├─clusterId	Long	The primary key ID of the cluster to which the tenant belongs in OCP.
├─obClusterId	Long	The ID of the cluster to which the tenant belongs in OceanBase Database.
├─clusterName	String	The name of the cluster to which the tenant belongs.
├─ocpClusterId	Long	The ID of the OCP cluster.
├─role	Enum	The role of the tenant. Valid values: PRIMARY: The tenant is the primary tenant. STANDBY: The tenant is a standby tenant. CLONE: The tenant is a cloned tenant. RESTORE: The tenant is being restored. The value automatically changes to `STANDBY` after the tenant is restored. UNKNOWN: The role of the tenant is unknown.
├─obVersion	String	The OceanBase Database version, with the build number, of the tenant.
├─obShortVersion	String	The four-digit OceanBase Database version of the tenant.
├─serviceName	String	The service name of the tenant.
├─logRestoreInfo	Object	The information about the log stream synchronization of the tenant.
├─serviceNameStatus	Enum	The status of the service name of the tenant. Valid values: VALID INVALID
├─ocpCluster	Object	The information about the OCP cluster that manages the tenant. This parameter takes effect only if you have deployed OCP in multi-cluster mode.
├─createTime	DateTime	The time when the tenant was created.
├─status	Enum	The status of the tenant. Valid values: NORMAL: The tenant is running. UNAVAILABLE: The tenant is unavailable. CREATING: The tenant is being created. OPERATING: The tenant is being operated. MODIFYING: The tenant is being modified. CLONING: The tenant is being cloned. RESTORING: The tenant is being restored. DISCONNECTING: The tenant is being disconnected. FAILOVER: The tenant is in a failover. SWITCHOVER: The tenant is in a switchover. MOVED_OUT: The tenant has been moved out. TDE_ENABLING: Transparent data encryption (TDE) is being enabled for the tenant.
├─locality	String	The replica distribution.
basicStandbyTenantList	Object	The standby tenants of the current tenant.
tags	Array	The tags for the tenant.
loadType	Enum	The type of the load. Valid values: EXPRESS_OLTP COMPLEX_OLTP HTAP OLAP KV

Examples

Sample request

Query tenants that are running or being created, and whose names contain the keyword "foo". Return only the second page, with a page size of 10.

GET /api/v2/ob/tenants?name=foo&status=NORMAL,CREATING&page=2&size=10

Sample response

{
    "data": {
        "contents": [{
            "clusterId": 6000004,
            "clusterName": "ob3233",
            "clusterStatus": "RUNNING",
            "clusterType": "PRIMARY",
            "createTime": "2025-03-20T12:09:15+08:00",
            "id": 6000006,
            "locality": "FULL{1}@zone1",
            "locked": false,
            "mode": "MYSQL",
            "name": "sys",
            "obClusterId": 1658110574,
            "obTenantId": 1,
            "obVersion": "3.2.3.3",
            "ocpClusterView": {
                "address": "http://xxx.xxx.xxxx.xxx:10550",
                "id": 10086,
                "lastHeartbeatTime": "2025-03-17T16:55:21.277+08:00",
                "name": "ocp-cluster",
                "role": "LEADER",
                "status": "NORMAL",
                "version": "4.3.6"
            },
            "primaryZone": "zone1",
            "readonly": false,
            "role": "PRIMARY",
            "status": "NORMAL",
            "syncStatus": "VALID",
            "zoneList": "zone1"
        }],
        "page": {
            "number": 1,
            "size": 5000,
            "totalElements": 1,
            "totalPages": 1
        }
    },
    "duration": 37,
    "server": "74f95ea2f4",
    "status": 200,
    "successful": true,
    "timestamp": "2025-03-20T16:47:00.342+08:00",
    "traceId": "629da8eaec66effe"
}