Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 143 additions & 0 deletions docs/guide/24-sql-primer.en.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
# SQL Primer: Three Statements From Table to Query

This page is for readers who have never used OpenTenBase before. It picks three basic SQL examples from the existing documentation, explains them line by line in the order "create a table, insert data, query data", and points out the parts that usually confuse newcomers.

> **How this page was verified**
>
> Every example is quoted from the OpenTenBase documentation, with its source given inline. All outputs are **expected results** derived from the documentation; the author did not execute these statements against a live cluster. To verify them on a real instance, see [Quick Start](01-quickstart.en.md).

## 1、Reading order

| Step | Statement | Question it answers | Example |
| --- | --- | --- | --- |
| 1 | `CREATE TABLE` | Where does the data live and how is it distributed? | Example 1 |
| 2 | `INSERT` | How do I write data into it? | Example 2 |
| 3 | `SELECT` | How do I read data back, and which nodes are touched? | Example 3 |

The order matters because OpenTenBase is a distributed database: the distribution strategy is decided when the table is created, and it affects the performance of every later read and write.

## 2、Example 1: create a replication table

**Source**: [`docs/guide/03-basic-use.md`](https://github.com/OpenTenBase/docs/blob/main/docs/guide/03-basic-use.md), section "1.3、Create repilication table"; rendered page: [Basic Usage](https://docs.opentenbase.org/en/guide/03-basic-use/).

```sql
create table public.t1_rep
(
f1 int not null,
f2 varchar(20),
primary key(f1)
)
distribute by replication
to group default_group;
```

Line by line:

| Code | What it does |
| --- | --- |
| `create table public.t1_rep` | Create table `t1_rep` in schema `public` |
| `f1 int not null` | Integer column, must not be null |
| `f2 varchar(20)` | Variable-length string, up to 20 characters |
| `primary key(f1)` | Primary key on `f1`, which also creates a primary key index |
| `distribute by replication` | Replication table: every DataNode keeps a full copy |
| `to group default_group` | Place it in the default storage group, that is, all DataNodes |

**Expected result**: `CREATE TABLE`.

**When to use it**: the same section says replication tables suit small tables that are frequently joined across nodes. It also lists two constraints: every node stores the full data set, so it does not suit large tables, and update performance is lower.

## 3、Example 2: insert two rows at once

**Source**: the same page, section "2.1、INSERT".

```sql
CREATE TABLE public.t1_insert_mul
(
f1 int not null,
f2 varchar(20),
primary key(f1)
) distribute by shard(f1) to group default_group;

INSERT INTO t1_insert_mul VALUES (1,'opentenbase'),(2,'pg');
```

Line by line:

| Code | What it does |
| --- | --- |
| `distribute by shard(f1)` | Shard table: the value of `f1` decides which DataNode holds the row |
| `to group default_group` | Use the default storage group, which contains several DataNodes |
| `INSERT INTO ... VALUES (...),(...)` | Insert two rows in one statement, with value groups separated by commas |
| `(1,'opentenbase')`、`(2,'pg')` | The two rows, in the column order given at creation time |

**Expected result**: `INSERT 0 2` (output quoted from the documentation, an expected result).

**A common misunderstanding**: because the table is sharded on `f1`, the row with `f1 = 1` and the row with `f1 = 2` may well land on different nodes. That is expected behaviour, not a half-finished insert.

## 4、Example 3: query by the distribution key

**Source**: the same page, section "2.4、SELECT".

```sql
explain select * from t1_select where f1=1;
```

Line by line:

| Code | What it does |
| --- | --- |
| `explain` | Show the plan only, without returning rows |
| `select *` | Select all columns |
| `from t1_select` | Read from the shard table created earlier |
| `where f1=1` | The condition hits the distribution key, so a single DataNode can be used |

**Expected result**: the plan contains `Node/s: dn001` and an `Index Scan` on that node (output quoted from the documentation, an expected result).

**Takeaway**: the same section states that queries on the distribution key have the best performance and scalability; conditions that do not hit it are sent to all nodes and then aggregated on the Coordinator.

## 5、The sentence that is hardest to read

The original documentation explains the syntax in two sentences:

> `distribute by shard(x)` specifies the distribution key: the value of this field decides which node holds the data.
>
> `to group xxx` specifies the storage group (each storage group may contain several nodes).

After reading that, newcomers still mix up three things: the distribution key, the storage group, and the primary key. The improved explanation:

| Concept | One-line explanation | In the example |
| --- | --- | --- |
| Distribution key | The column whose value decides which DataNode stores a row | `f1` in `shard(f1)` |
| Storage group | A set of DataNodes the table may use | `default_group` |
| Primary key | Guarantees row uniqueness; unrelated to distribution | `primary key(f1)` |

> **Do not mistake an analogy for a technical fact**
>
> You can picture it as "split students by the last digit of their ID (distribution key) and only use these buildings (storage group)", but the analogy only builds intuition. The real sharding rule is a hash computation; refer to the documentation and source code for exact behaviour.

## 6、Exercises

1. Rewrite Example 1 as a shard table on `f1`. What should the `distribute by` line become?
Check: `distribute by shard(f1)`, everything else unchanged.
2. After the insert in Example 2, what is the expected result of `select count(*) from t1_insert_mul;`?
Check: two rows were inserted, so the expected value is 2.
3. What happens with `update t1_insert_mul set f1 = 3 where f1 = 1;`?
Check: `f1` is the distribution key and cannot be updated. The documentation shows `ERROR: Distributed column or partition column "f1" can't be updated in current version`.

## 7、Source cross-check

| Explanation | Basis | Result |
| --- | --- | --- |
| Replication tables store full data on every node, suit small tables, and update slowly | 03-basic-use.md, section 1.3 | Consistent |
| `distribute by shard(f1)` distributes by the field value | 03-basic-use.md, section 1.1 | Consistent |
| Creating a replication table outputs `CREATE TABLE` | 03-basic-use.md, section 1.3 code block | Consistent |
| Multi-row insert outputs `INSERT 0 2` | 03-basic-use.md, section 2.1 code block | Consistent |
| A query on the distribution key touches one DataNode | 03-basic-use.md, section 2.4 EXPLAIN output | Consistent |
| The distribution key cannot be updated | 03-basic-use.md, section 2.2 error example | Consistent |

## 8、References

- [Basic Usage (source)](https://github.com/OpenTenBase/docs/blob/main/docs/guide/03-basic-use.en.md)
- [Basic Usage (rendered)](https://docs.opentenbase.org/en/guide/03-basic-use/)
- [Quick Start](01-quickstart.en.md)
- [Application Access](02-access.en.md)
160 changes: 160 additions & 0 deletions docs/guide/24-sql-primer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
# SQL 入门手册:从建表到查询的三条语句

本文面向第一次接触 OpenTenBase 的读者,从仓库已有文档中选取 3 条最基础的 SQL 示例,按“建表 → 写入 → 查询”的顺序解释每一行在做什么、为什么这样写,并给出新手最常见的困惑点。

> **关于本文的验证方式**
>
> 本文示例均摘自 OpenTenBase 文档库,出处逐条标注。所有输出均为按文档说明推导的**预期结果**,本文作者未在集群上实际执行这些 SQL;如需真实验证,请参考[快速入门](01-quickstart.md)搭建实例。

## 1、阅读顺序

| 顺序 | 语句类型 | 先解决什么问题 | 对应示例 |
| --- | --- | --- | --- |
| 第一步 | `CREATE TABLE` | 数据放在哪、怎么分布 | 示例一 |
| 第二步 | `INSERT` | 怎么把数据写进去 | 示例二 |
| 第三步 | `SELECT` | 怎么把数据查出来、走哪些节点 | 示例三 |

先建表再写入最后查询,是因为 OpenTenBase 是分布式数据库,表建好时就已经决定了数据分布方式,后续读写性能都受它影响。

## 2、示例一:建一张复制表

**来源**:[`docs/guide/03-basic-use.md`](https://github.com/OpenTenBase/docs/blob/main/docs/guide/03-basic-use.md) 的“1.3、创建复制表”一节,在线页面:[基本使用](https://docs.opentenbase.org/guide/03-basic-use/)。

```sql
create table public.t1_rep
(
f1 int not null,
f2 varchar(20),
primary key(f1)
)
distribute by replication
to group default_group;
```

逐行解释:

| 代码 | 作用 |
| --- | --- |
| `create table public.t1_rep` | 在 `public` 模式下建表,表名 `t1_rep` |
| `f1 int not null` | 第一列,整型,不允许为空 |
| `f2 varchar(20)` | 第二列,最长 20 个字符的可变长字符串 |
| `primary key(f1)` | 主键是 `f1`,同时会创建主键索引 |
| `distribute by replication` | 复制表:每个 DN 节点都保存一份全量数据 |
| `to group default_group` | 放进默认存储组,即所有 DN 节点 |

**预期结果**:`CREATE TABLE`。

**为什么用复制表**:文档同一节给出的适用场景是“经常要跨库 JOIN 的小数据量表”;同时明确了两条约束——所有节点都有全量数据,因此不适合大数据表;复制表的更新性能较低。

## 3、示例二:一次插入两行

**来源**:同一文档的“2.1、INSERT”一节。

```sql
CREATE TABLE public.t1_insert_mul
(
f1 int not null,
f2 varchar(20),
primary key(f1)
) distribute by shard(f1) to group default_group;

INSERT INTO t1_insert_mul VALUES (1,'opentenbase'),(2,'pg');
```

逐行解释:

| 代码 | 作用 |
| --- | --- |
| `distribute by shard(f1)` | 分片表,按 `f1` 的值计算哈希,决定这一行落到哪个 DN |
| `to group default_group` | 使用默认存储组(包含多个 DN 节点) |
| `INSERT INTO t1_insert_mul VALUES (...),(...)` | 一条语句插入两行,逗号分隔多个值组 |
| `(1,'opentenbase')`、`(2,'pg')` | 两行数据,列顺序与建表时一致 |

**预期结果**:`INSERT 0 2`(文档原文输出,属预期结果)。

**新手容易忽略的点**:因为是按 `f1` 分片,`f1 = 1` 和 `f1 = 2` 的两行很可能落在不同节点上,这是正常现象,不是“数据只写进去了一半”。

## 4、示例三:带分布键的查询

**来源**:同一文档的“2.4、SELECT”一节。

```sql
explain select * from t1_select where f1=1;
```

逐行解释:

| 代码 | 作用 |
| --- | --- |
| `explain` | 只显示执行计划,不真正返回数据行 |
| `select *` | 查询所有列 |
| `from t1_select` | 查询前面建好的分片表 |
| `where f1=1` | 条件命中分布键 `f1`,可以定位到单个 DN |

**预期结果**:执行计划中出现 `Node/s: dn001`,并在该节点上走 `Index Scan`(文档原文输出,属预期结果)。

**关键结论**:文档在同一节明确“基于分布键查询性能最优、扩展性好”;反过来,不命中分布键的条件会被发往所有节点,再在 CN 汇总。

## 5、把最难懂的一句讲清楚

原文档对建表语法的说明只有两句话:

> `distribute by shard(x) 用于指定分布键,数据分布于那个节点就是根据这个字段值来计算分片。`
>
> `to group xxx 用于指定存储组(每个存储组可以有多个节点)。`

新手读完仍然容易混淆三件事:分布键、存储组、主键。改进后的对照说明如下。

| 概念 | 一句话解释 | 在本例中 |
| --- | --- | --- |
| 分布键 | 决定某一行去哪个 DN 的字段 | `shard(f1)` 中的 `f1` |
| 存储组 | 一批 DN 的集合,表只在这些节点上分布 | `default_group` |
| 主键 | 保证这一行唯一,与数据分布是两件事 | `primary key(f1)` |

> **别把类比当技术事实**
>
> 可以把它想象成“按学号尾号分班(分布键)+ 只在这几栋教学楼里分(存储组)”,但类比只帮助建立直觉;实际分片规则是哈希计算,具体行为以文档和源码为准。

**改进前后对比**:

| 维度 | 原说明 | 改进后 |
| --- | --- | --- |
| 概念数量 | 一句话里塞了分布键、节点、存储组 | 拆成 3 行表格,一概念一行 |
| 主键是否参与分布 | 未提及 | 明确“主键与分布是两件事” |
| 可自查性 | 读完无法确认 | 每行都对应示例中的具体字段 |

## 6、小练习

1. 把示例一的复制表改成按 `f1` 分片的表,`distribute by` 那行应该怎么写?
自查要点:应改为 `distribute by shard(f1)`,其余不变。
2. 执行示例二的插入后,`select count(*) from t1_insert_mul;` 的预期结果是多少?
自查要点:插入 2 行,预期为 2。
3. 如果执行 `update t1_insert_mul set f1 = 3 where f1 = 1;` 会发生什么?
自查要点:`f1` 是分布键,文档“2.2、UPDATE”明确分布键不能更新,会报 `Distributed column or partition column “f1” can't be updated in current version`。

## 7、逐项核对

| 解释条目 | 依据 | 核对结果 |
| --- | --- | --- |
| 复制表每节点全量、不适合大表、更新性能低 | 03-basic-use.md“1.3、创建复制表”说明段 | 一致 |
| `distribute by shard(f1)` 按字段值计算分片 | 03-basic-use.md“1.1、创建 shard 普通表”说明段 | 一致 |
| 复制表建表预期输出 `CREATE TABLE` | 03-basic-use.md“1.3”代码块 | 一致 |
| 多行插入预期输出 `INSERT 0 2` | 03-basic-use.md“2.1、INSERT”代码块 | 一致 |
| 分布键查询走单个 DN | 03-basic-use.md“2.4、SELECT”的 EXPLAIN 输出 | 一致 |
| 分布键不可更新 | 03-basic-use.md“2.2、UPDATE”报错示例 | 一致 |

> **试读反馈(待补)**
>
> 按任务要求需请另一组同学试读并记录一条反馈。当前记录模板如下,提交 PR 前需补齐:
>
> - 试读者:
> - 读完后用自己的话复述“分布键”:
> - 卡住的位置:
> - 建议:

## 8、参考

- [基本使用(文档源文件)](https://github.com/OpenTenBase/docs/blob/main/docs/guide/03-basic-use.md)
- [基本使用(在线页面)](https://docs.opentenbase.org/guide/03-basic-use/)
- [快速入门](01-quickstart.md)
- [应用接入](02-access.md)
2 changes: 2 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ nav:
- 用户指南:
- OpenTenBase:
- 快速入门: guide/01-quickstart.md
- SQL 入门手册: guide/24-sql-primer.md
- 应用接入: guide/02-access.md
- 基本使用: guide/03-basic-use.md
- 高级使用: guide/04-advanced-use.md
Expand Down Expand Up @@ -142,6 +143,7 @@ plugins:
首页: Home
用户指南: Guide
快速入门: Quick Start
SQL 入门手册: SQL Primer
概述: Overview
安装指南: Deploy
应用接入: Application Access
Expand Down