📝 docs(tsl): rebuild canonical syntax and routing manual

2026-04-22 16:59:20 +08:00
parent 3ed5052e61
commit 96b705b00b
83 changed files with 46446 additions and 323 deletions
@@ -0,0 +1,120 @@
+# TS-SQL
+
+文档类型：语法主线
+是否可直接用于生成代码：是
+是否含已验证可执行示例：是
+是否含已验证反例：否
+遇到不确定时跳转到：[28_ts_sql_core.md](28_ts_sql_core.md)、[29_ts_sql_advanced.md](29_ts_sql_advanced.md)、[14_resultset_and_filters.md](14_resultset_and_filters.md)
+
+手册位置：第 15 篇，共 32 篇。上一篇：[14_resultset_and_filters.md](14_resultset_and_filters.md)。下一篇：[16_debug_and_profiler.md](16_debug_and_profiler.md)。
+
+这一篇不再只是跳转页。它负责把 TS-SQL 放回整个语言阅读主线里：先知道它是什么、最短骨架怎么写、什么时候继续进入 `28` 和 `29` 两篇专题。
+
+## 这一篇解决什么问题
+
+回答“第一次进入 TS-SQL 时，应该先记住哪些固定骨架，怎样区分基础查询和高级查询，以及哪些内容属于语法、哪些已经属于业务层数据访问”。
+
+## 必须记住的规则
+
+- TS-SQL 是 TSL 自带的类 SQL 查询语法，不是金融业务函数库。
+- 基础查询当前的稳定骨架是：以 `select` / `sselect` / `vselect` / `mselect` 开始，以 `end` 收尾。
+- 在内存二维结果集上，当前稳定字段访问写法是 `["字段名"]`。
+- 在一维数组上做 TS-SQL 时，当前应优先使用 `ThisRow` 和 `ThisRowIndex`。
+- `select` 返回二维结果，`sselect` 返回一维结果，`vselect` 返回单值，`mselect` 返回 `Matrix`。
+- `join`、`ThisGroup`、`RefMaxOf` / `RefMinOf` 这类更深查询，已经进入进阶页，不要和入门骨架混写。
+- 访问金融表、时间序列或业务数据源时，语法和业务语义要分开看；本页只讲语言层查询骨架。
+
+## 已验证语法
+
+### 最小查询骨架
+
+代码块身份：已验证可执行示例
+
+```tsl
+program test;
+begin
+    T := array(
+        ("A": 1, "B": 3),
+        ("A": 2, "B": 1)
+    );
+    R := select * from T end;
+end.
+```
+
+已验证运行结果：
+
+- `R` 的长度是 `2`
+- 两行依次是 `(1,3)`、`(2,1)`
+- 说明 TS-SQL 的最短可靠入口就是“准备结果集，然后 `select ... from T end`”
+
+### 四个查询入口怎样分工
+
+代码块身份：已验证可执行示例
+
+```tsl
+program test;
+begin
+    T := array(
+        ("A": 1, "B": 3),
+        ("A": 2, "B": 1),
+        ("A": 1, "B": 2)
+    );
+    S := sselect ["A"] from T end;
+    V := vselect sumof(["B"]) from T end;
+    M := mselect * from T end;
+    C := MCols(M, 1);
+end.
+```
+
+已验证运行结果：
+
+- `sselect ["A"] from T end` 返回一维数组 `array(1, 2, 1)`
+- `vselect sumof(["B"]) from T end` 返回单值 `6`
+- `mselect * from T end` 的行数是 `3`、列数是 `2`
+- `MCols(M, 1)` 返回列索引 `array("A", "B")`
+
+### 什么时候进入进阶页
+
+当查询开始出现多表字段、联接条件或组内子查询时，就不要继续停留在本页：
+
+代码块身份：已验证可执行示例
+
+```tsl
+program test;
+begin
+    A := array(
+        ("ID": 1, "V1": 10),
+        ("ID": 2, "V1": 20)
+    );
+    B := array(
+        ("ID": 1, "V2": 100),
+        ("ID": 3, "V2": 300)
+    );
+    R := select [1].["ID"], [1].["V1"], [2].["V2"]
+         from A join B on [1].["ID"] = [2].["ID"]
+         end;
+end.
+```
+
+已验证运行结果：
+
+- `R` 的长度是 `1`
+- 唯一一行是 `(1,10,100)`
+- 说明一旦开始写 `[1].["字段"]`、`join`、`on` 这类结构，就已经进入 [29_ts_sql_advanced.md](29_ts_sql_advanced.md) 的责任范围
+
+## 暂不在本页展开的部分
+
+- `with on`
+- `insert` / `update` / `delete`
+- 面向 SQL 表或业务表的数据写回
+- 时间序列查询选项
+- 更深的缓存、对象化接口和写回类
+
+这些内容不是不能写，而是应先去对应专题页或业务文档，不要在这篇入门页提前固化成默认模板。
+
+## 跳转指引
+
+- 如果你其实要先做结果集过滤：去 [14_resultset_and_filters.md](14_resultset_and_filters.md)
+- 如果你刚开始写 TS-SQL：先去 [28_ts_sql_core.md](28_ts_sql_core.md)
+- 如果你已经需要 `join` / `ThisGroup` / `RefMaxOf`：去 [29_ts_sql_advanced.md](29_ts_sql_advanced.md)
+- 如果你其实是在做业务查询任务：去 [../finance/index.md](../finance/index.md)