Skip to content

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

Open

Description

@shibuchou

问题

docs/guide/01-quickstart.md 里包含新用户第一次在 OpenTenBase 上执行的 SQL:

create table foo(id bigint, str text) distribute by shard(id);
insert into foo values(1, 'tencent'), (2, 'shenzhen');
select * from foo;

这三条语句和 shell 命令、psql 元命令、执行输出挤在同一个代码块里,而且没有任何解释。第一次读的人得自己推断:

  • 为什么提示符从 postgres=# 变成了 test=>;
  • 为什么 distribute by shard(id) 会出现在建表语句里;
  • INSERT 里的两组括号分别是什么;
  • 查出来的两行是否保证按这个顺序返回。

如果另写一份解释,还会带来维护问题:快速入门一改,解释就会悄悄和它引用的原文对不上。

建议

  1. 新增 docs/guide/first-three-sql.md:只针对这三条已有语句的简短伴读,保留原始 SQL 不改。每条包含用途、原句、逐段解释、前置条件、明确标注的预期结果、常见误解,以及固定到某个提交的来源链接。
  2. 从快速入门链接到它。只加一行,不改动原有 SQL 和展示的输出。
  3. 新增 tools/sql_guide/:仅用标准库的离线校验器,当引用的语句与原文不一致时报告。不执行 SQL,不访问网络。

范围

  • 不执行 SQL,不改数据库或部署。
  • 不是通用 Markdown/SQL 解析器:只处理这三条单行示例,只识别 postgres=# 和 test=> 两种提示符。
  • 不依赖模型或 API,不自动改写。
  • 校验器验证的是引用一致性,不是技术正确性。

验收

  • 三条来源比较全部通过,并覆盖负向用例:字符串字面量被改、字符串内部空格不同、语句缺失、语句歧义、标记缺失、标记重复、清单非法。
  • 五个下一步链接逐一点击验证,不只检查文件是否存在。
  • 伴读不暗示没有 ORDER BY 也会有固定顺序。
  • 原有快速入门的 SQL 及其展示输出保持不变。

想请维护者确认

这样一份伴读,加上一个可选的校验脚本,放在 OpenTenBase/docs 里有用吗?如果觉得校验脚本多余,伴读本身可以单独合并。

对应的 PR 已经提了:#69。方向需要调整的话,我在 PR 上改。

Activity

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions