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