oceanbase-sql-doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OceanBase SQL Documentation Skill

OceanBase SQL文档编写技能

This skill provides guidelines for writing OceanBase database SQL statement documentation following the official documentation standards.

本技能提供遵循官方文档标准的OceanBase数据库SQL语句文档编写指南。

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

在以下场景中使用本技能：

编写SQL语句参考文档
编辑现有SQL文档
创建SQL语句示例
格式化SQL语法文档

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.

所有文档必须以元信息表开头（而非YAML前置内容）：

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

默认规则：仅填写必要字段（description、keywords）。仅在适用时填写tenant-type字段。

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

用途 - 简要说明该语句的功能
语法 - SQL语法定义（不含分号）
参数 - 表格形式的参数说明
示例 - 可执行的SQL示例及执行结果
参考文档 - 相关文档的链接

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:

sql

ALTER SYSTEM KILL SESSION 'session_id, serial#';

语法定义结尾不加分号
语法用于说明格式/结构，而非可执行语句
使用带有
```
sql
```
语言标签的代码块

示例：

sql

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:

sql

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

SQL语句：

SQL语句前添加
```
obclient>
```
或
```
obclient [SCHEMA]>
```
提示符
可执行语句中包含分号
SQL语句放在单独的代码块中

查询结果：

查询结果放在单独的代码块中
使用“查询结果如下：”或“Query results:”连接SQL语句与结果
除非有帮助，否则不要包含“Query OK”消息
除非有意义，否则不要包含“Query OK, 0 rows affected”之类的内容

示例格式：

sql

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

示例中使用有意义的名称（而非
```
t1
```
、
```
tg1
```
这类简单名称）
表组：
```
order_tg
```
、
```
product_tg
```
表：
```
order_table
```
、
```
user_info
```
数据库：使用具有业务含义的名称
这有助于用户理解实际业务场景

Notice boxes

提示框

说明 (Explain):

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

注意 (Notice):

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

说明 (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

在最终确定文档前，请检查：

元信息表格式正确
语法章节无分号
示例使用
```
obclient>
```
前缀
SQL语句与结果放在单独的代码块中
示例名称具有业务含义
提示框使用正确格式
文档全程间距规范
无多余的“Query OK”消息
所有代码块都有合适的语言标签

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>

使用表格形式展示参数：

参数名称	说明
session_id	当前会话的客户端会话ID。该ID是客户端中会话的唯一标识。 <main id="notice" type='explain'><h4>说明</h4><p>您可以执行<code>SHOW PROCESSLIST;</code>或<code>SHOW FULL PROCESSLIST</code>语句查看<code>session_id</code>。 </p></main>

Reference links

参考链接

Format references as:

markdown

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

参考链接格式如下：

markdown

有关如何查询当前数据库中会话的数量和ID的更多信息，请参见[查看租户会话](../../../../../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

当sql_parser文件与测试用例不一致时：

始终遵循测试用例 - 它们反映了实际的生产功能
测试用例展示了用户实际可以使用的功能
记录真实可用的语法，而非理论上的解析器定义