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

Read-only queries

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

When to use
Prerequisites
Procedure
Typical example
What to do next

OAgent supports initiating read-only SQL queries against business tenants or the system tenant (sys) within a conversation. It also supports using EXPLAIN to view execution plans, aiding in data verification and plan confirmation. All queries are executed in read-only mode and do not affect the database.

When to use

  • Confirm the row count, size, partition distribution, or column structure of a table.
  • Verify business data, such as querying the number of orders or status distribution for a specific period.
  • Use EXPLAIN to verify whether an SQL statement hits the expected index or performs a full table scan.
  • Query internal views (such as the gv$ and __all_ series) in the sys tenant to troubleshoot cluster-level issues.

Prerequisites

  • You have configured a connection for the product to which the target cluster belongs. For queries from a business tenant, you need to configure access credentials for that tenant; for queries from the system tenant, you need to configure a connection with sys tenant privileges. For details, see Create a product connection.

  • You have selected the target cluster and tenant in the session using @. For more information, see Use @ to reference analysis objects.

Note

The permissions for read-only queries are controlled by the whitelist configured in the OCP system. Currently, only SELECT and EXPLAIN statements are allowed; write operations such as INSERT/UPDATE/DELETE/DDL will not be executed. For security reasons, do not grant write command permissions; configure only the read-only feature.

Procedure

  1. Select the target cluster and tenant in the session using @.

  2. Describe your query requirement. You can either provide the SQL directly or describe it in natural language to let the Agent generate the SQL:

    Check the data volume of table t_order for the last 24 hours.
    Total rows and partition distribution of table t_user in business tenant xxx
    EXPLAIN SELECT * FROM t_order WHERE create_time > '2026-08-01'
    Check the current active minor compaction tasks in the sys tenant.
    
  3. Press Enter to send the request and wait for the Agent to return the result.

    • The Agent first confirms the target tenant and database, then executes the query in read-only mode.
    • For EXPLAIN requests, the Agent returns the execution plan and highlights key information such as full table scans and index selections.
  4. View the returned result.

    • Regular query results are displayed in a table format with automatically adjusted column widths.
    • EXPLAIN results include operator interpretation. For details, see Execution plan interpretation.

Typical example

query: Find the total number of rows and the number of rows in each partition for the table t_order under the business tenant retail.

The Agent will generate and execute a read-only query similar to the following:

```sql
SELECT COUNT(*) FROM t_order;
SELECT partition_id, COUNT(*) FROM t_order GROUP BY partition_id;
```

And returns the total number of rows and the distribution of partition row counts in a table.

What to do next

  • If the query result does not meet expectations (for example, the returned row count deviates significantly from the estimate), it may be due to outdated statistics. For more information, see Diagnose statistics issues.

  • To turn frequent verification queries into periodic tasks, see Create a scheduled task.

Previous topic

Query resource metrics and task status
Last

Next topic

Alert query and troubleshooting guide
Next
on this page
When to use
Prerequisites
Procedure
Typical example
What to do next