OceanBase SQL Documentation Skill

This skill provides guidelines for writing OceanBase database SQL statement documentation following the official documentation standards.

When to use

Use this skill when:

• •Writing SQL statement reference documentation
• •Editing existing SQL documentation
• •Creating examples for SQL statements
• •Formatting SQL syntax documentation

Document structure

Meta information table

All documents must start with a meta information table (not YAML frontmatter):

Default: Only fill in necessary fields (description, keywords). Fill tenant-type only when applicable.

Standard sections

1. •Purpose - Brief description of what the statement does
2. •Syntax - SQL syntax definition (without semicolon)
3. •Parameters - Parameter descriptions in table format
4. •Examples - Executable SQL examples with results
5. •References - Links to related documentation

Formatting rules

Syntax section

• •Syntax definitions end WITHOUT semicolons
• •Syntax is for format/structure explanation, not executable statements
• •Use code blocks with sql language tag

Example:

ALTER SYSTEM KILL SESSION 'session_id, serial#';

Examples section

SQL Statements:

• •Prefix SQL statements with obclient> or obclient [SCHEMA]> prompt
• •Include semicolons in executable statements
• •Place SQL statements in separate code blocks

Query Results:

• •Place query results in separate code blocks
• •Connect SQL and results with text like "查询结果如下：" or "Query results:"
• •Do NOT include "Query OK" messages unless helpful
• •Do NOT include "Query OK, 0 rows affected" or similar unless meaningful

Example Format:

obclient [KILL_USER]> SHOW PROCESSLIST;

查询结果如下：

+------------+-----------+----------------------+-----------+---------+------+--------+------------------+
| ID         | USER      | HOST                 | DB        | COMMAND | TIME | STATE  | INFO             |
+------------+-----------+----------------------+-----------+---------+------+--------+------------------+
| 3221487726 | KILL_USER | 100.xx.xxx.xxx:34803 | KILL_USER | Query   |    0 | ACTIVE | SHOW PROCESSLIST |
+------------+-----------+----------------------+-----------+---------+------+--------+------------------+
1 row in set

Naming conventions

• •Use meaningful names in examples (not simple names like t1, tg1)
• •Table groups: order_tg, product_tg
• •Tables: order_table, user_info
• •Databases: Use business-meaningful names
• •This helps users understand real-world application scenarios

Notice boxes

说明 (Explain):

注意 (Notice):

Spacing rules

• •Space between title and body text
• •Space between body text and code blocks/tables
• •Space between sections

Quality checklist

Before finalizing documentation:

• • Meta information table is properly formatted
• • Syntax section has no semicolons
• • Examples use obclient> prefix
• • SQL statements and results are in separate code blocks
• • Example names are meaningful and business-oriented
• • Notice boxes use correct format
• • Proper spacing throughout document
• • No unnecessary "Query OK" messages
• • All code blocks have appropriate language tags

Common patterns

Parameter tables

Use table format for parameters:

Reference links

Format references as:

For more information about how to query the quantity and IDs of sessions in the current database, see [View tenant sessions](../../../../../1200.database-proxy/1500.view-tenant-sessions.md).

Testing against test cases

When sql_parser files and test cases differ:

• •Always follow test cases - they reflect actual production functionality
• •Test cases show what users can actually use
• •Document the real, working syntax, not theoretical parser definitions