oceanbase-syntax

name	oceanbase-syntax
description	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.
license	MIT
metadata	{"audience":"technical-writers","domain":"sql-syntax"}

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:

ALTER SYSTEM KILL SESSION 'session_id, serial#'

ALTER SYSTEM KILL SESSION 'session_id' [IMMEDIATE]

Incorrect:

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:

ALTER SYSTEM KILL SESSION 'session_id' [IMMEDIATE]

Multiple options

Use pipe | for alternatives:

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

Repetition

Use ... for repeating elements:

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

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

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:

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

SHOW PROCESSLIST

With options

SHOW [FULL] PROCESSLIST

With multiple clauses

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

With subclauses

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

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

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