oceanbase-sql-doc（oceanbase SQL DOC 开发）

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