OceanBase
English日本語简体中文
Docs Home
Products
Integrations
Release Notes

Databases

OceanBase DatabaseOceanBase AI DatabaseOceanBase Cloud OceanBase Best Practices

Tools

OceanBase Cloud PlatformOceanBase Migration ServiceOceanBase Developer CenterOceanBase Migration AssessmentOceanBase Admin ToolOceanBase Loader and DumperOceanBase DeployerKubernetes operator for OceanBaseOceanBase Diagnostic Tool OceanBase Binlog ServiceOceanBase DataPilotOceanBase OAgent

Connectors and Middleware

OceanBase Database Proxy OceanBase Connector/C OceanBase Connector/J OceanBase Connector/ODBC OceanBase Connector/NETOceanBase Command-Line Client

Databases

OceanBase DatabaseOceanBase AI DatabaseOceanBase Cloud OceanBase Best Practices

Connectors and Middleware

OceanBase Database Proxy OceanBase Connector/C OceanBase Connector/J OceanBase Connector/ODBC OceanBase Connector/NETOceanBase Command-Line Client

Tools

OceanBase Cloud PlatformOceanBase Migration ServiceOceanBase Developer CenterOceanBase Migration AssessmentOceanBase Admin ToolOceanBase Loader and DumperOceanBase DeployerKubernetes operator for OceanBaseOceanBase Diagnostic Tool OceanBase Binlog ServiceOceanBase DataPilotOceanBase OAgent
OceanBase DatabaseOceanBase Cloud ToolsConnectors and MiddlewareLifecycle Support Policy

OceanBase OAgent

V2.2.0
  • Product overview
    • What is OAgent?
    • Key features
    • System architecture
    • Use cases
  • Quick start
  • Deployment
  • Overview
  • Sessions and diagnosis
    • Manage sessions
    • Switch dialogue models
    • Use @ to mention the analysis target
    • View the tool invocation process
    • Upload an attachment
    • Data visualization
    • FAQ
    • Export a report
  • Tools
  • Skill Management
  • Channel management
  • Knowledge base
    • Built-in knowledge base
    • Custom knowledge base
  • Scheduled tasks
    • Overview of scheduled tasks
    • Create a scheduled task
  • View usage
  • Model configuration
    • Manage model services
    • Model scoring
  • Settings and security
    • Product management
    • Experimental features
  • Best practices
    • Perform a cluster health inspection
    • Query cluster and topology information
    • Query resource metrics and task status
    • Read-only queries
    • Alert query and troubleshooting guide
    • Root cause analysis of exceptions
    • ASH diagnostic report
    • Analyze slow SQL, TopSQL, and abnormal SQL
    • SQL pre-analysis and tuning recommendations
    • Interpret execution plans
    • Diagnostic information statistics
    • Parameter check and change governance
    • Database change ticket
  • Appendix
    • Feature list
    • Built-in Skills
  • Release notes
    • OAgent V2.2.0 Release note
    • OAgent V2.1.0 Release note
    • OAgent V2.0.0 Release note
    • OAgent V1.8.0 Release note

Download PDF

Document Feedback
  1. Documentation Center
  2. OceanBase OAgent
  3. V2.2.0

Query cluster and topology information

Last Updated:2026-11-20 07:25:11

When to use
Prerequisites
Procedure
Typical example
What to do next

OAgent supports querying basic information about OceanBase clusters, tenants, and databases, as well as the topology distribution of Zones, Servers, and Units, using natural language in conversations. You can obtain structured results by describing your target without having to log in to the OCP console and browse pages one by one.

When to use

  • When taking over an unfamiliar cluster, you need to quickly understand its tenants, databases, and node distribution.
  • When troubleshooting resource allocation or primary/standby distribution issues, you need to confirm whether the distribution of Units across Zones/Servers is balanced.
  • To confirm the tenant mode (MySQL/Oracle), Primary Zone, and locality configuration of a tenant.

Prerequisites

  • You have configured an OCP connection for the product to which the target cluster belongs. For details, see Create a product connection.

  • The target cluster and tenant have been selected with @ in the current session context. See Use @ to mention the analysis object.

Procedure

  1. On the Create a conversation page, enter @ and select the target product and cluster.

  2. Enter your query based on your purpose, for example:

    Check what tenants this cluster has and their respective modes.
    What is the Zone and Server distribution in this cluster?
    List the databases under tenant xxx.
    On which Servers are the Units in this cluster distributed?
    
  3. Press Enter to send the request and wait for the Agent to call the tools and return the results.

    The Agent will call tools such as ocp_cluster, ocp_tenant, ocp_database, and ocp_topology based on your request. Multiple queries can be chained in a single round of conversation.

  4. View the returned results.

    • Cluster information typically includes the cluster ID, version, number of tenants, status, etc.
    • Topology information usually lists the Servers, Regions, status, and number of Units in each Zone in a table format.
    • If the distribution is significantly uneven, the Agent will add a prompt after the result.

Typical example

query: Check the Zone/Server/Unit distribution in this cluster to see if it is balanced.

Agent will first obtain the cluster topology, then count the number of Units on each Server, and output a conclusion similar to the following:

| Zone | Server | Number of Units | Status |
|---|---|---|---|
| zone1 | ***.***.***.**1:2882 | 5 | active |
| zone2 | ***.***.***.**2:2882 | 6 | active |
| zone3 | ***.***.***.**3:2882 | 3 | active |

It is noted that the number of units in zone3 is significantly lower. It is recommended to check whether unit migration is required.

What to do next

  • If uneven unit distribution is detected, you can continue the same session to inquire about migration recommendations or capacity utilization. For more information, see Query resource metrics and task status.

  • To perform a comprehensive health check, you can directly initiate a cluster health inspection. For more information, see Cluster health inspection.

Previous topic

Perform a cluster health inspection
Last

Next topic

Query resource metrics and task status
Next
on this page
When to use
Prerequisites
Procedure
Typical example
What to do next