oceanbase-examples

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OceanBase Documentation Examples

OceanBase文档示例

This skill provides guidelines for creating SQL examples in OceanBase documentation.

本技能提供了在OceanBase文档中创建SQL示例的规范指南。

Example structure

示例结构

SQL statements

SQL语句

Always prefix with prompt:

```
obclient>
```
for default prompt
```
obclient [SCHEMA]>
```
when schema context is relevant

Include semicolons in executable statements.

Example:

sql

obclient [KILL_USER]> SHOW PROCESSLIST;

始终添加前缀提示符：

```
obclient>
```
为默认提示符
当涉及Schema上下文时使用
```
obclient [SCHEMA]>
```

可执行语句需包含分号。

示例：

sql

obclient [KILL_USER]> SHOW PROCESSLIST;

Query results

查询结果

Separate from SQL statements:

Place SQL in one code block
Place results in another code block
Connect with descriptive text like "查询结果如下：" or "Query results:"

Example:

sql

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

与SQL语句分开展示：

将SQL放在一个代码块中
将查询结果放在另一个代码块中
使用“查询结果如下：”或“Query results:”这类描述性文字连接两者

示例：

sql

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

使用有意义的名称

Avoid simple names:

❌
```
t1
```
,
```
t2
```
,
```
tg1
```
,
```
db1
```
❌
```
test_table
```
,
```
temp_db
```

Use business-meaningful names:

✅ Table groups:
```
order_tg
```
,
```
product_tg
```
,
```
inventory_tg
```
✅ Tables:
```
order_table
```
,
```
user_info
```
,
```
product_catalog
```
✅ Databases:
```
sales_db
```
,
```
customer_db
```
,
```
warehouse_db
```

Why:

Helps users understand real-world scenarios
Makes examples more relatable
Demonstrates practical applications

避免使用简化名称：

❌
```
t1
```
,
```
t2
```
,
```
tg1
```
,
```
db1
```
❌
```
test_table
```
,
```
temp_db
```

使用具备业务含义的名称：

✅ 表组：
```
order_tg
```
,
```
product_tg
```
,
```
inventory_tg
```
✅ 表：
```
order_table
```
,
```
user_info
```
,
```
product_catalog
```
✅ 数据库：
```
sales_db
```
,
```
customer_db
```
,
```
warehouse_db
```

原因：

帮助用户理解真实场景
让示例更易理解
展示实际应用

Example scenarios

示例场景

E-commerce:

Tables:
```
orders
```
,
```
order_items
```
,
```
customers
```
,
```
products
```
Table groups:
```
order_tg
```
,
```
product_tg
```
Databases:
```
ecommerce_db
```

Financial:

Tables:
```
transactions
```
,
```
accounts
```
,
```
balances
```
Table groups:
```
transaction_tg
```
,
```
account_tg
```
Databases:
```
banking_db
```

Inventory:

Tables:

warehouses

inventory_items

stock_movements

Table groups:
```
warehouse_tg
```
,
```
inventory_tg
```
Databases:
```
logistics_db
```

电商场景：

表：
```
orders
```
,
```
order_items
```
,
```
customers
```
,
```
products
```
表组：
```
order_tg
```
,
```
product_tg
```
数据库：
```
ecommerce_db
```

金融场景：

表：
```
transactions
```
,
```
accounts
```
,
```
balances
```
表组：
```
transaction_tg
```
,
```
account_tg
```
数据库：
```
banking_db
```

库存场景：

表：

warehouses

inventory_items

stock_movements

表组：
```
warehouse_tg
```
,
```
inventory_tg
```
数据库：
```
logistics_db
```

What to include

需包含的内容

Include:

需要包含：

✅ Query result tables (when helpful)
✅ Error messages (when demonstrating error handling)
✅ Descriptive output (when it adds value)

✅ 查询结果表（有帮助时）
✅ 错误信息（演示错误处理时）
✅ 描述性输出（能提供价值时）

Exclude:

需要排除：

❌ "Query OK" messages
❌ "Query OK, 0 rows affected"
❌ "Query OK, 1 row affected"
❌ Generic success messages

Exception: Only include these if they provide meaningful information for understanding the example.

❌ "Query OK" 类消息
❌ "Query OK, 0 rows affected"
❌ "Query OK, 1 row affected"
❌ 通用成功提示

例外情况： 仅当这类信息对理解示例有实际意义时才可以包含。

Example workflow

示例流程

Step 1: Create context

步骤1：创建上下文

Set up meaningful scenario:

sql

obclient [SYS]> CREATE USER sales_user IDENTIFIED BY 'password123';
obclient [SYS]> GRANT CREATE SESSION TO sales_user;
obclient [SYS]> CREATE DATABASE sales_db;
obclient [SYS]> USE sales_db;

搭建有意义的场景：

sql

obclient [SYS]> CREATE USER sales_user IDENTIFIED BY 'password123';
obclient [SYS]> GRANT CREATE SESSION TO sales_user;
obclient [SYS]> CREATE DATABASE sales_db;
obclient [SYS]> USE sales_db;

Step 2: Create objects

步骤2：创建对象

Use meaningful names:

sql

obclient [SALES_DB]> CREATE TABLE order_table (
    order_id BIGINT PRIMARY KEY,
    customer_id BIGINT,
    order_date DATE,
    total_amount DECIMAL(10,2)
);

使用有意义的命名：

sql

obclient [SALES_DB]> CREATE TABLE order_table (
    order_id BIGINT PRIMARY KEY,
    customer_id BIGINT,
    order_date DATE,
    total_amount DECIMAL(10,2)
);

Step 3: Demonstrate feature

步骤3：演示功能特性

Show the SQL statement:

sql

obclient [SALES_DB]> SELECT * FROM order_table WHERE order_date >= '2024-01-01';

展示SQL语句：

sql

obclient [SALES_DB]> SELECT * FROM order_table WHERE order_date >= '2024-01-01';

Step 4: Show results

步骤4：展示结果

Separate code block with descriptive text:

查询结果如下：

+----------+-------------+------------+--------------+
| order_id | customer_id | order_date | total_amount |
+----------+-------------+------------+--------------+
|      101 |        1001 | 2024-01-15 |      1250.00 |
|      102 |        1002 | 2024-01-20 |       850.50 |
+----------+-------------+------------+--------------+
2 rows in set

使用描述性文字分隔代码块：

查询结果如下：

+----------+-------------+------------+--------------+
| order_id | customer_id | order_date | total_amount |
+----------+-------------+------------+--------------+
|      101 |        1001 | 2024-01-15 |      1250.00 |
|      102 |        1002 | 2024-01-20 |       850.50 |
+----------+-------------+------------+--------------+
2 rows in set

Complex examples

复杂示例

Multi-step examples

多步骤示例

For complex workflows, break into logical steps:

Step 1: Setup

sql

obclient [SYS]> CREATE USER admin_user IDENTIFIED BY 'admin123';
obclient [SYS]> GRANT ALTER SYSTEM TO admin_user;

Step 2: Create table group

sql

obclient [ADMIN_USER]> CREATE TABLEGROUP order_tg;

Step 3: Create table

sql

obclient [ADMIN_USER]> CREATE TABLE order_table (
    order_id BIGINT PRIMARY KEY,
    customer_id BIGINT
) TABLEGROUP = order_tg;

Step 4: Verify

sql

obclient [ADMIN_USER]> SHOW TABLEGROUPS;

查询结果如下：

+-----------+------------+
| TableName | TableGroup |
+-----------+------------+
| order_table | order_tg  |
+-----------+------------+
1 row in set

对于复杂工作流，拆分为逻辑步骤：

步骤1：环境搭建

sql

obclient [SYS]> CREATE USER admin_user IDENTIFIED BY 'admin123';
obclient [SYS]> GRANT ALTER SYSTEM TO admin_user;

步骤2：创建表组

sql

obclient [ADMIN_USER]> CREATE TABLEGROUP order_tg;

步骤3：创建表

sql

obclient [ADMIN_USER]> CREATE TABLE order_table (
    order_id BIGINT PRIMARY KEY,
    customer_id BIGINT
) TABLEGROUP = order_tg;

步骤4：验证结果

sql

obclient [ADMIN_USER]> SHOW TABLEGROUPS;

查询结果如下：

+-----------+------------+
| TableName | TableGroup |
+-----------+------------+
| order_table | order_tg  |
+-----------+------------+
1 row in set

Error examples

错误示例

When demonstrating error handling:

sql

obclient [USER]> CREATE TABLE invalid_table (
    id INT PRIMARY KEY,
    name VARCHAR(10)
) PARTITION BY HASH(id) PARTITIONS 0;

错误信息如下：

ERROR 1235 (42000): Invalid partition count

演示错误处理时：

sql

obclient [USER]> CREATE TABLE invalid_table (
    id INT PRIMARY KEY,
    name VARCHAR(10)
) PARTITION BY HASH(id) PARTITIONS 0;

错误信息如下：

ERROR 1235 (42000): Invalid partition count

Best practices

最佳实践

Start simple, add complexity gradually
Use consistent naming throughout example
Show realistic data in results
Include comments when helpful (but keep them concise)
Test examples to ensure they work
Follow test cases when they differ from parser definitions

从简单开始，逐步增加复杂度
整个示例中使用统一的命名规范
结果中展示真实合理的数据
有帮助时添加注释（但保持简洁）
测试示例确保可正常运行
当测试用例与解析器定义不一致时，遵循测试用例

Quality checklist

质量检查清单

SQL statements have
```
obclient>
```
prefix
SQL and results in separate code blocks
Meaningful, business-oriented names used
No unnecessary "Query OK" messages
Results formatted clearly
Example demonstrates real-world usage
All statements are executable and tested

SQL语句带有
```
obclient>
```
前缀
SQL和结果放在独立的代码块中
使用有意义的面向业务的命名
无多余的"Query OK"消息
结果格式清晰
示例演示真实场景用法
所有语句可执行且经过测试