OceanBase SQL Documentation Skill

When to use

• Writing SQL statement reference documentation
• Editing existing SQL documentation
• Creating examples for SQL statements
• Formatting SQL syntax documentation

Document structure

Meta information table

Standard sections

1. Purpose - Brief description of what the statement does
2. Syntax - SQL syntax definition (without semicolon)
3. Parameters - Parameter descriptions in table format
4. Examples - Executable SQL examples with results
5. References - Links to related documentation

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

ALTER SYSTEM KILL SESSION 'session_id, serial#';

Examples section

• Prefix SQL statements with

  obclient>

  or

  obclient [SCHEMA]>

  prompt
• Include semicolons in executable statements
• Place SQL statements in separate code blocks

• 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

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

Notice boxes

Spacing rules

• Space between title and body text
• Space between body text and code blocks/tables
• Space between sections

Quality checklist

• 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

Common patterns

Parameter tables

Reference links

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

Testing against test cases

• 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