oceanbase-syntax

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OceanBase SQL Syntax Documentation

OceanBase SQL语法文档

This skill provides guidelines for writing SQL syntax sections in OceanBase documentation.

本技能为OceanBase文档中SQL语法章节的编写提供指导规范。

Key principle

核心原则

Syntax sections define structure, not executable statements.

语法章节仅定义结构，而非可执行语句。

Syntax section rules

语法章节规则

No semicolons

不使用分号

Syntax definitions end WITHOUT semicolons:

Correct:

sql

ALTER SYSTEM KILL SESSION 'session_id, serial#'

ALTER SYSTEM KILL SESSION 'session_id' [IMMEDIATE]

Incorrect:

sql

ALTER SYSTEM KILL SESSION 'session_id, serial#';

ALTER SYSTEM KILL SESSION 'session_id' [IMMEDIATE];

语法定义结尾不能加分号：

正确示例：

sql

ALTER SYSTEM KILL SESSION 'session_id, serial#'

ALTER SYSTEM KILL SESSION 'session_id' [IMMEDIATE]

错误示例：

sql

ALTER SYSTEM KILL SESSION 'session_id, serial#';

ALTER SYSTEM KILL SESSION 'session_id' [IMMEDIATE];

Why no semicolons?

为何不使用分号？

Syntax sections explain format and structure
They are not directly executable statements
Semicolons are statement terminators, not part of syntax definition
Examples section shows executable statements with semicolons

语法章节用于说明格式与结构
它们并非可直接执行的语句
分号是语句终止符，不属于语法定义的一部分
示例部分会展示带分号的可执行语句

Syntax notation

语法符号说明

Optional parameters

可选参数

Use square brackets

[]

for optional parameters:

sql

ALTER SYSTEM KILL SESSION 'session_id' [IMMEDIATE]

使用方括号

[]

表示可选参数：

sql

ALTER SYSTEM KILL SESSION 'session_id' [IMMEDIATE]

Multiple options

多选项

Use pipe

for alternatives:

sql

CREATE TABLE table_name (
    column_name data_type [NOT NULL | NULL]
)

使用竖线

表示互斥选项：

sql

CREATE TABLE table_name (
    column_name data_type [NOT NULL | NULL]
)

Repetition

重复元素

Use

...

for repeating elements:

sql

CREATE TABLE table_name (
    column_name data_type,
    ...
)

使用

...

表示可重复的元素：

sql

CREATE TABLE table_name (
    column_name data_type,
    ...
)

Required vs optional

必填与可选区分

No brackets = required
```
[brackets]
```
= optional
```
{braces}
```
= required group (if used)
```
|
```
= alternative choice

无括号 = 必填项
```
[方括号]
```
= 可选项
```
{大括号}
```
= 必填组（若使用）
```
|
```
= 互斥选项

Syntax section structure

语法章节结构

Basic format

基础格式

markdown

undefined

markdown

undefined

Syntax

语法

sql

STATEMENT_NAME parameter1 [optional_parameter]

undefined

sql

STATEMENT_NAME parameter1 [optional_parameter]

undefined

Complex syntax

复杂语法

For multi-line syntax:

sql

CREATE TABLE table_name (
    column_name data_type [column_constraint],
    ...
) [table_option]

对于多行语法：

sql

CREATE TABLE table_name (
    column_name data_type [column_constraint],
    ...
) [table_option]

Multiple syntax variants

多语法变体

When multiple forms exist:

sql

ALTER SYSTEM KILL SESSION 'session_id, serial#';

ALTER SYSTEM KILL SESSION 'session_id' [IMMEDIATE];

Note: Even in syntax section, show variants with semicolons separated, but the syntax definition itself doesn't need semicolons if showing the pattern.

当存在多种语法形式时：

sql

ALTER SYSTEM KILL SESSION 'session_id, serial#';

ALTER SYSTEM KILL SESSION 'session_id' [IMMEDIATE];

注意：即使在语法章节中展示多变体，若呈现的是语法模式，定义本身仍无需分号；若分开展示变体，可带分号。

Examples section

示例章节

Examples ARE executable and include semicolons:

sql

obclient [KILL_USER]> ALTER SYSTEM KILL SESSION '3221487726';

示例是可执行的，需包含分号：

sql

obclient [KILL_USER]> ALTER SYSTEM KILL SESSION '3221487726';

Parameter descriptions

参数说明

After syntax, provide parameter table:

Parameter	Description
session_id	The Client Session ID of the current session.
serial#	This parameter is not implemented in the current version and is reserved only for syntax compatibility.
IMMEDIATE	Immediately switches back to the specified session to execute `KILL` . This parameter is optional.

语法之后需提供参数说明表：

参数	说明
session_id	当前会话的客户端会话ID。
serial#	该参数在当前版本未实现，仅为语法兼容性保留。
IMMEDIATE	立即切换到指定会话执行 `KILL` 操作，此参数为可选。

Common patterns

常见语法模式

Simple statement

简单语句

sql

SHOW PROCESSLIST

sql

SHOW PROCESSLIST

With options

带选项的语句

sql

SHOW [FULL] PROCESSLIST

sql

SHOW [FULL] PROCESSLIST

With multiple clauses

带多子句的语句

sql

CREATE TABLE table_name (
    column_definition,
    ...
) [table_options]

sql

CREATE TABLE table_name (
    column_definition,
    ...
) [table_options]

With subclauses

带子子句的语句

sql

ALTER TABLE table_name
    ADD column_name data_type [AFTER existing_column]

sql

ALTER TABLE table_name
    ADD column_name data_type [AFTER existing_column]

Testing syntax

语法验证

Important: When sql_parser files and test cases differ:

Follow test cases - they reflect actual functionality
Test cases show what users can actually use
Document real, working syntax

重要提示： 当sql_parser文件与测试用例不一致时：

以测试用例为准——它们反映了实际功能
测试用例展示了用户实际可使用的内容
需记录真实可用的语法

Quality checklist

质量检查清单

Common mistakes

常见错误

❌ Adding semicolons to syntax

❌ 为语法添加分号

sql

ALTER SYSTEM KILL SESSION 'session_id';  # Wrong

sql

ALTER SYSTEM KILL SESSION 'session_id';  # 错误

❌ Mixing syntax and examples

❌ 混淆语法与示例

Don't show executable examples in syntax section.

不要在语法章节中展示可执行示例。

❌ Inconsistent notation

❌ 符号使用不一致

Use consistent notation throughout:

```
[]
```
for optional
```
|
```
for alternatives
```
...
```
for repetition

始终保持符号使用一致：

```
[]
```
表示可选
```
|
```
表示互斥选项
```
...
```
表示重复

Best practices

最佳实践

Keep syntax concise - show structure, not implementation details
Use clear notation - standard SQL syntax notation
Provide parameter table - explain each parameter
Match test cases - document what actually works
Separate syntax from examples - different sections, different rules

保持语法简洁——仅展示结构，而非实现细节
使用清晰符号——遵循标准SQL语法符号
提供参数说明表——解释每个参数的含义
匹配测试用例——记录实际可用的语法
区分语法与示例——不同章节遵循不同规则