Repository navigation
Conversation
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.
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
关联 #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.mddocs/guide/images/first-three-sql-flow.svgdocs/guide/01-quickstart.mdtools/sql_guide/check.pytools/sql_guide/examples.jsontools/sql_guide/README.mdtools/sql_guide/tests/test_check.py图用 SVG 而不是 Mermaid,是因为本站的
pymdownx.superfences没有配custom_fences,写 Mermaid 代码块只会被渲染成一段代码;SVG 不用改mkdocs.yml,也不用加构建依赖,同时是纯文本,评审时能直接看 diff。定位与比对
sql围栏。行号只出现在报告里,所以编辑文档不会让校验失效。'shen zhen'和'shenzhen'会判失败,不会被归一化后放过。0全过,1文档或定位有问题,2参数或清单不合法。1是改文档,2是改配置,分开能少一半误会。sql围栏、来源匹配到两条以上,全部按失败报告。实测
Python 3.11.6,在本分支上实跑:
在仓库外复制一份临时副本,把 INSERT 里的
'shenzhen'改成'Shanghai':恢复后重新运行回到
0。git diff --check干净,快速入门的 diff 只有一行新增。三条语句没有在集群上执行,所以伴读里的输出标为“来源文档展示”或“预期结果”,不写成实测;
SELECT没有ORDER BY,文中也直说了顺序不保证。校验器比对的是引用文本,解释对不对仍要靠人读。页面没有加进
mkdocs.yml导航,从快速入门点进来就能看到;需要导航项的话我加。英文翻译也留作后续,免得这个 PR 越滚越大。