Skip to content

docs: 新增《SQL 入门手册》——3 条基础 SQL 逐句解释 - #70

Open
zgl-www wants to merge 3 commits into
OpenTenBase:mainfrom
zgl-www:docs/sql-primer
Open

zgl-www wants to merge 3 commits into
OpenTenBase:mainfrom
zgl-www:docs/sql-primer

Conversation

@zgl-www

@zgl-www zgl-www commented Nov 7, 2026

Copy link
Copy Markdown

PR:新增《SQL 入门手册》——为 3 条基础 SQL 补充逐句解释

对应题目方向 1「帮新手读懂第一条 SQL——SQL 入门手册」。

这个 PR 做了什么

新增一页面向第一次接触 OpenTenBase 的读者文档,从既有文档 docs/guide/03-basic-use.md 中选取 3 条最基础的 SQL 示例,按「建表 → 写入 → 查询」的学习顺序补充用途说明、逐行解释、预期结果和小练习,并给出与源文档的逐条核对表。

同时提供英文版(仓库要求 *.en.md 同目录存放),并在 mkdocs.yml 中挂到「用户指南 → OpenTenBase」下、紧跟「快速入门」,以及英文 nav_translations。

变更文件

文件 变更 说明
docs/guide/24-sql-primer.md 新增 中文正文,约 150 行
docs/guide/24-sql-primer.en.md 新增 英文对照版
mkdocs.yml 修改 导航新增一条 + 英文翻译条目

为什么是这 3 条

  1. 覆盖三种最基础的操作:CREATE TABLE ... distribute by replication(分布方式)、INSERT(写入)、SELECT ... explain(查询与路由),正好是新手的第一个闭环。
  2. 都来自同一节:03-basic-use.md,读者读完本文可以顺势读原文,不用跳来跳去。
  3. 踩中新手最容易混的点:复制表 vs 分片表、分布键 vs 主键、命中分布键的查询为什么快。

与题目要求的对应

题目要求 本文对应
3 条 SQL 逐步解释 第 2、3、4 节,每条含逐行解释表
标明示例来源 每节开头给出源文件链接 + 小节名 + 在线页面链接
小练习 第 6 节,3 题并附自查要点
语法标注 / 示意表格 逐行解释表、阅读顺序表、概念对照表
自行推导的结果标为「预期结果」 每处输出前明确写「预期结果」;开头的 note 说明未实际执行
对照来源核对解释 第 7 节核对表,逐条给出依据小节
请另一组试读并记录反馈 待补,模板已写入第 7 节

展示方式:一个新手原本不易理解的例子

原文对建表语法的说明是两句长句,同时出现「分布键」「节点」「存储组」三个概念,读完仍不知道三者的关系。本文第 5 节把它拆成:

  • 一张三行对照表(分布键 / 存储组 / 主键,各自一句话 + 在本例中对应哪个字段)
  • 一个生活类比,并用 warning 明确「别把类比当技术事实」
  • 一张改进前后对比表(概念数量、主键是否参与分布、可自查性)

验证记录

已执行的检查:

  • 逐条核对源文档:复制表适用场景与约束、distribute by shard 语义、INSERT 0 2、Node/s: dn001、分布键不可更新,均与 03-basic-use.md 一致(见正文第 7 节)
  • 本地实建站点验证:拉取 OpenTenBase/docs 后按本 PR 修改 mkdocs.yml,用 mkdocs-material + mkdocs-static-i18n 构建,zh 与 en 两个页面均生成成功(各约 54 KB),导航中出现「SQL 入门手册」,正文渲染出 7 张表格、3 个代码块,构建日志没有本文件的告警
  • 构建中发现并修正一处问题:本仓库的 mkdocs.yml 把 markdown_extensions 写在 theme: 下,admonition 扩展实际未启用,!!! note 会原样输出。因此正文改用引用块(>)承载提示与警告,重建后确认页面中不再出现字面量 !!!
  • 格式自查(依据 contribution/docs-format-guide.md):正文无多余一级标题、代码块均指定 sql 语言、表格与代码块前后留空行、中英文之间加空格、引用块内容有缩进
  • 相对链接目标存在:01-quickstart.md、02-access.md 均与本文同目录
  • 中英文件名符合规范:24-sql-primer.en.md

未执行、需 reviewer 协助:

  • 在仓库 CI 或 PR 预览中点击导航与所有链接,确认跳转正确(本地构建已通过,但仍建议在真实站点复核)
  • 请另一位同学试读正文第 5 节,用自己的话复述「分布键」,把反馈填进第 7 节的模板

预览

mkdocs serve

导航位置:用户指南 → OpenTenBase → SQL 入门手册。

已知限制

  • 本文未在真实集群执行 SQL,所有输出均为「预期结果」,这与题目「不要求实际执行 SQL」一致;若有 reviewer 愿意补一次真实执行截图,会在后续 commit 中追加。
  • 英文版为直译,术语沿用英文文档现有译法(Coordinator / DataNode / distribution key)。

@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants