oceanbase-sql-doc

name	oceanbase-sql-doc
description	Write and format OceanBase database SQL statement documentation following official style guidelines. Use when creating or editing SQL reference documentation for OceanBase database.
license	MIT
metadata	{"audience":"technical-writers","domain":"database-documentation"}

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

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:

Parameter	Description
session_id	The Client Session ID of the current session. This ID is the unique identifier of the session in the client. Note You 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