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

注意 (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:

Parameter	Description
session_id	The Client Session ID of the current session. This ID is the unique identifier of the session in the client. NoteYou can execute the SHOW PROCESSLIST; or SHOW FULL PROCESSLIST statement to view the session_id.

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

oceanbase-sql-doc