oceanbase-syntax

Original：🇺🇸 English

Translated

Write SQL syntax definitions for OceanBase documentation. Syntax sections define structure without semicolons, while examples show executable statements. Use when writing syntax sections or reviewing SQL statement documentation.

2installs

Sourceamber-moe/oceanbase-doc-skills

Added on2026-02-28

NPX Install

npx skill4agent add amber-moe/oceanbase-doc-skills oceanbase-syntax

SKILL.md Content

View Translation Comparison →

OceanBase SQL Syntax Documentation

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

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];

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]

Multiple options

Use pipe

for alternatives:

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

Required vs optional

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

Syntax section structure

Basic format

markdown

## Syntax

```sql
STATEMENT_NAME parameter1 [optional_parameter]


### Complex syntax

For multi-line syntax:

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

Examples section

Examples ARE executable and include semicolons:

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.

Common patterns

Simple statement

sql

SHOW PROCESSLIST

With options

sql

SHOW [FULL] PROCESSLIST

With multiple clauses

sql

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

With subclauses

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

Quality checklist

Syntax section has NO semicolons
Examples section HAS semicolons
Optional parameters in brackets
Clear notation for alternatives
Parameter table provided
Syntax matches test cases (not just parser)
Formatting is consistent

Common mistakes

❌ Adding semicolons to syntax

sql

ALTER SYSTEM KILL SESSION 'session_id';  # Wrong

❌ 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