Skip to content

docs: add first SQL walkthrough with source consistency checks - #69

Open
shibuchou wants to merge 6 commits into
OpenTenBase:mainfrom
shibuchou:docs/first-three-sql
Open

shibuchou wants to merge 6 commits into
OpenTenBase:mainfrom
shibuchou:docs/first-three-sql

Conversation

@shibuchou

@shibuchou shibuchou commented Nov 7, 2026 •

Copy link
Copy Markdown

关联 #68,合并后自动关闭(Closes #68)。

01-quickstart.md 的“使用”小节给了三条 SQL,读者第一次见,却没有任何解释:提示符为什么从 postgres=# 变成 test=>,distribute by shard(id) 为什么写在建表语句里,INSERT 的两组括号分别是什么,查出来的两行顺序能不能依赖。

这个 PR 给这三条语句配一份伴读,再配一个离线校验器。伴读里的语句是从原文逐字抄的,原文一改、伴读没跟上,校验器会报出来并指到具体行。

三条语句的阅读顺序与执行路径

图的上半部分是执行路径:客户端连 CN,CN 把语句下发到各个 DN,再把结果汇总回来。下半部分是阅读顺序:建表拿到表结构,插入才有地方放数据,查询才有内容可读。图中没有把某一行画到某个 DN 上——distribute by shard(id) 只规定“由 id 计算落点”,实际落点看分片规则和节点数量。

改动

文件 作用
docs/guide/first-three-sql.md 伴读:用途、原句、逐段解释、前置条件、预期结果、常见误解、固定来源链接、五个下一步入口
docs/guide/images/first-three-sql-flow.svg 上面这张图
docs/guide/01-quickstart.md 加一行指向伴读的链接,原有 SQL 和输出一行没动
tools/sql_guide/check.py 离线校验器,只用标准库
tools/sql_guide/examples.json 三个示例的 ID 和来源定位键
tools/sql_guide/README.md 用法、退出码、比对规则、限制
tools/sql_guide/tests/test_check.py 28 个测试

图用 SVG 而不是 Mermaid,是因为本站的 pymdownx.superfences 没有配 custom_fences,写 Mermaid 代码块只会被渲染成一段代码;SVG 不用改 mkdocs.yml,也不用加构建依赖,同时是纯文本,评审时能直接看 diff。

定位与比对

  • 不用行号定位。 来源侧按“提示符 + 语句开头”在代码围栏内匹配,伴读侧用 HTML 注释 ID 绑定紧随其后的 sql 围栏。行号只出现在报告里,所以编辑文档不会让校验失效。
  • 比对逐字来。 只去掉提示符和行首行尾空白,大小写、字符串内部空格、标点都照原样比。'shen zhen' 和 'shenzhen' 会判失败,不会被归一化后放过。
  • 退出码分三档。 0 全过,1 文档或定位有问题,2 参数或清单不合法。1 是改文档,2 是改配置,分开能少一半误会。
  • 不静默跳过。 未知标记 ID、重复标记、多行代码块、非 sql 围栏、来源匹配到两条以上,全部按失败报告。

实测

Python 3.11.6,在本分支上实跑:

$ python3 tools/sql_guide/check.py --root .
sql-guide source consistency check
  manifest: tools/sql_guide/examples.json
  source:   docs/guide/01-quickstart.md
  guide:    docs/guide/first-three-sql.md

PASS  create-foo-table       guide:40 <- source:312
PASS  insert-foo-rows        guide:77 <- source:314
PASS  select-foo-all         guide:113 <- source:316

summary: 3 examples, 3 passed, 0 failed
$ python3 -m unittest discover -s tools/sql_guide/tests
............................
----------------------------------------------------------------------
Ran 28 tests in 1.979s

OK

在仓库外复制一份临时副本,把 INSERT 里的 'shenzhen' 改成 'Shanghai':

FAIL  insert-foo-rows
      reason: statement differs from source at column 44 (source line 314)
      guide:  docs/guide/first-three-sql.md:77
      source: docs/guide/01-quickstart.md:314
      expected: insert into foo values(1, 'tencent'), (2, 'shenzhen');
      actual:   insert into foo values(1, 'tencent'), (2, 'Shanghai');

恢复后重新运行回到 0。git diff --check 干净,快速入门的 diff 只有一行新增。

三条语句没有在集群上执行,所以伴读里的输出标为“来源文档展示”或“预期结果”,不写成实测;SELECT 没有 ORDER BY,文中也直说了顺序不保证。校验器比对的是引用文本,解释对不对仍要靠人读。

页面没有加进 mkdocs.yml 导航,从快速入门点进来就能看到;需要导航项的话我加。英文翻译也留作后续,免得这个 PR 越滚越大。

The quickstart shows three SQL statements with psql prompts and sample
output, but never explains them statement by statement, and a separate
explanation can silently drift from the text it quotes.

Add a companion guide for exactly those three existing statements and an
offline checker that reports when the quoted statements drift.

- docs/guide/first-three-sql.md: reading order for CREATE TABLE, INSERT
  and SELECT, with prerequisites, labelled expected results, common
  misunderstandings, pinned source links and five next-step entries
- docs/guide/01-quickstart.md: one link to the guide; the existing SQL
  and sample output are unchanged
- tools/sql_guide/{check.py,examples.json,README.md}: standard-library
  only, offline, never executes SQL; text and JSON output; exit code 0
  on a full match, 1 on document or locator problems, 2 on invalid
  arguments or invalid manifest
- tools/sql_guide/tests/test_check.py: 28 tests covering the happy path,
  string drift, whitespace inside literals, missing and ambiguous source
  statements, broken or duplicate guide markers, invalid manifests and
  the JSON report

The checker validates reference consistency only. It does not claim the
explanation is technically correct, and it does not run any SQL.
@CLAassistant

CLAassistant commented Nov 7, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

The three statements, their order and the CN/DN path were only described
in prose and a table. Add one diagram showing the reading order and the
execution path.

The diagram deliberately does not place individual rows on individual
DNs: distribute by shard(id) only defines how a row is located from its
id, and the actual placement depends on the distribution rule and the
number of nodes. A caption repeats that limit so the drawing cannot be
read as a claim about data placement.

SVG is used so the figure stays reviewable as text (6.8 KB, no binary
blob) and renders in the existing mkdocs build without new extensions.
The paragraph after the figure only said what the drawing does not
claim, which left the reader to work the figure out alone. Replace it
with what the drawing actually shows: the client/CN/DN path on top, the
three-step chain below, and the reason no individual row is drawn onto a
node.

Rename the closing scope section to plain language and drop the
disclaimer phrasing.
The label on each statement already says the output is quoted from the
source document; repeating "(原文照录,本文未执行)" after every one of
them only adds noise. State the rule once at the top and drop the
repetitions.
…re caption belongs to the document, not the image

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.

docs: explain the first three SQL examples and check their source consistency

2 participants