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):

| Description | | |---------------|-----------------| | description | 文档的内容描述。注意：句尾需要统一加句号。 | | keywords | 关键词，多个关键词之间用英文逗号隔开 | | dir-name | 这里填写希望在国内站文档中心目录上展示的名称 | | dir-name-en | 这里填写希望在海外站文档中心目录上展示的名称 | | tenant-type | MySQL Mode 或 Oracle Mode（两种模式均适用则不填写） | | ddl-type | Online DDL 或 Offline DDL（仅适用于内核 SQL 语句相关文档） | | machine-translation | 标识机器翻译的文档（如有） |

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

Standard sections

Purpose - Brief description of what the statement does
Syntax - SQL syntax definition (without semicolon)
Parameters - Parameter descriptions in table format
Examples - Executable SQL examples with results
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):

<main id="notice" type='explain'> <h4>说明</h4> <p>用于解释复杂概念、提供背景信息或详细说明。使用此格式传达重要解释性内容。</p> </main>

注意 (Notice):

<main id="notice" type='notice'> <h4>注意</h4> <p>用于突出显示警告、限制或重要提示。强调用户需特别关注的信息。</p> </main>

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:

| Parameter | Description | |-----------------|------------------------------------------------------------| | session_id | The Client Session ID of the current session. This ID is the unique identifier of the session in the client. <main id="notice" type='explain'><h4>Note</h4><p>You can execute the <code>SHOW PROCESSLIST;</code> or <code>SHOW FULL PROCESSLIST</code> statement to view the <code>session_id</code>. </p></main> |

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