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