sybn sql 执行模型与命令分类总览

• content

概述

sybn sql 是基于 SQL-92 扩展的多语句流水线查询语言。它在标准 SQL 基础上增加了三类能力：

1. 流水线——多条语句用分号 ; 连接，前一条的结果自动传递给后一条。
2. 非标命令——20+ 个扩展命令，覆盖列操作、行列转换、批量执行、缓存、调试等场景。
3. 异构数据源——可在一条 SQL 中联合查询 mysql、mongo、es、redis、json、csv 等。

本文是 sybn sql 的执行模型总览，适合作为 nl2sql（自然语言转 SQL）应用的命令选择参考。

一、流水线执行模型

1.1 分号多语句

sybn sql 用分号 ; 连接多条语句，按顺序执行：

select * from users where age > 18;
appendColumns(now() as query_time);
removeColumns(password);

执行流程：

1. 第一条 select 查询用户表，结果压入堆栈。
2. 第二条 appendColumns 从堆栈取出结果，追加 query_time 列，新结果压栈。
3. 第三条 removeColumns 从堆栈取出结果，删除 password 列，新结果压栈。
4. 最终返回栈顶结果。

1.1.1 流水线承接规则（重要）

流水线只有最后一个语句的结果会返回，且多语句之间必须有承接关系——后一条语句必须能消费前一条压栈的结果。每条命令对堆栈有明确的「消费量 / 生产量」（见 1.2 节分类）：

多步骤查询的正确写法：用一条 select + 子查询 + 转换命令组合。如果需要合并两个独立查询结果，用 join（而不是串联两个 select）。如果确实需要分步，用 execBatch 或 cacheResult 承接。

1.2 堆栈机制

每条语句执行后，结果会被压入一个 stackData 堆栈：

语句1: select ...     →  压栈 [结果1]
语句2: appendColumns  →  弹出[结果1], 处理后压栈 [结果2]
语句3: removeColumns  →  弹出[结果2], 处理后压栈 [结果3]
                                   ↑ 最终返回

• 默认返回栈顶（最后一条语句的结果）。
• return 命令可以指定返回堆栈中的任意一层。
• clearQueue 命令可以清空堆栈。

1.3 命令的流水线行为分类（核心）

每条命令对 stackData 堆栈有明确的「消费量 / 生产量」，这是判断能否承接的依据（对应源码 SySqlCommandConverExecutor.getConsumed()）：

消费量来自源码：ConvertSySqlJoin.getConsumed()=2、SySqlExecBatchQueryExecutor.getConsumed()=1、SySqlClearQueueQueryExecutor.getConsumed()=Integer.MAX_VALUE，convert 类命令通过 SySqlCommandConverExecutor 接口默认消费 1 个。

1.4 子查询嵌套：() 包裹多语句流水线

核心模式：用 () 包裹一个多语句流水线，外层可以接标准 SQL 操作（where / group by / order by / having / limit 等），把流水线结果当作一张表来用。

/* 把用户表和订单 join 后, 外层再按城市分组聚合 */
select city, sum(total) as city_total
from (
  /* 第1步: 左表 */
  select id, name, city from users where status = 1;
  /* 第2步: 右表 */
  select user_id, sum(amount) as total from orders group by user_id;
  /* 第3步: join 消费栈顶2个, 输出1个 */
  left join select(name, city, total) on left.id = right.user_id
) where total > 100          /* 外层过滤 */
group by city                /* 外层分组 */
order by city_total desc     /* 外层排序 */
limit 10;

关键规则：

1. () 内部是独立流水线，有自己的堆栈，内部多语句必须有承接关系（source → convert/multi-input）。
2. () 内部最终返回栈顶，作为外层 from 的数据源。
3. 外层可以接任意标准 SQL 子句：where / group by / having / order by / limit / join 等。
4. () 内部两个独立 select 串联会报错（select 1; select 2 无承接），必须用 join 或转换命令承接。

适用场景：多步骤处理（join/转换）后还需要用标准 SQL 做聚合、过滤、排序时，用 () 包裹流水线，外层写标准 SQL。这比把所有逻辑塞进流水线更清晰。

嵌套层级：() 可以多层嵌套，每层都是独立流水线：

select * from (
  select * from (
    select ...;
    select ...;
    join ...
  ) where ...               /* 内层流水线 + 外层过滤 */
  group by ...
) where ...                  /* 外层再过滤 */
order by ...

二、命令分类体系

sybn sql 的命令分为 7 大类，nl2sql 时根据意图选择。分类按功能划分；按流水线行为（source/convert/multi-input）划分见 1.3 节。

2.1 查询类（DQL，source）

标准 SQL 查询，产生新数据压栈。from 子句支持多种数据源（库表 + 字面量）。

标准库表查询：

内联字面量数据源（无需查库，数据写在 SQL 里，源码 TableLoader.loadList()）：

CSV/TSV 用三反引号文本块包裹，第一行表头（列名），其后数据行。详见 from factory 和 web-sql part2。

跨轮次对话数据合并：把上一轮查询结果手动复制为 JSON/CSV 字面量嵌入当前 SQL，用 join 或 union 合并（详见 from-factory 文档）。

/* 本轮数据 union 上一轮结果(JSON字面量) */
select '本轮' as round, cinema_name, amount from orders where date = curdate()
union all
select '上轮' as round, cinema_name, amount
from [{cinema_name:"影城A", amount:1200}, {cinema_name:"影城B", amount:980}]

2.2 转换类（convert，后置命令）

作用于前一条语句的结果，消费栈顶 1 个，转换后压栈 1 个。不改变行数（除 unwind/unnest）。

2.3 join 类（multi-input，后置命令）

消费栈顶 2 个（左表 + 右表），join 后输出 1 个结果压栈。前面必须有 2 条 source 语句。源码：ConvertSySqlJoin.getConsumed()=2。

示例：

/* 将用户表和订单表 join 起来 */
select * from (
  select id, name from users;
  select user_id, sum(amount) as total from orders group by user_id;
  left join select(name, total) on left.id = right.user_id
) order by total desc

语法说明：

• SELECT(...)：指定返回字段，支持 as 别名和 udf 函数；左右表同名字段优先返回左表值
• ON：支持 left.x = right.y、x = y、using(字段)；多条件用 AND 连接
• 报错信息：join 需要2张前表,而不是N张.可能是前面的某行代码少写了分号.
• 详见 DatasSqlJoinUtil

2.4 后置过滤类

作用于子查询结果，语法比嵌套 select 更简洁。

三者可组合：from (...) where 条件 order by 字段 limit N

2.5 子查询执行类（source / 旁路）

执行一个子 SQL，把结果压栈。常用于批量、动态数据源、缓存。

2.6 控制流类（control-flow / stack-control）

控制流水线的执行流程。不产生数据。

2.7 辅助类（auxiliary）

不产生数据，用于变量、表结构查看。

三、@变量传递机制

sybn sql 支持 5 种变量，是流水线语句间数据传递的核心：

3.1 特殊上下文变量（自动注入）

这些变量由系统自动注入，引用堆栈中的历史结果：

select * from users;
select count(*) as cnt from @sybn_last_select@table;
/* @sybn_last_select@table 被替换为上一条 select 的结果 */

3.2 用户变量（set 赋值）

set @t := str_to_date('2026-01-01', '%Y-%m-%d');
select * from orders where create_time > @t;

• 兼容 := 和 = 赋值。
• 一般只能替换 where 右侧的值。

3.3 列表变量

set @types@list := (select type from config where enabled = 1);
select * from orders where type in (@types@list);

• @var@list 用于 in 查询传值。
• 把子查询结果展开为列表。

3.4 外部参数（mybatis 风格）

select * from users where name = ${name} and age > ${age}

• ${var} 由 sql 外部传入，可替换任意位置。
• #{var} 同样支持（预编译占位）。

3.5 全局变量

select * from ${${env}_table}

• $${var} 引用全局变量，可替换任意位置。

四、执行顺序图解

┌─────────────────────────────────────────────────────────┐
│  输入: 多语句 SQL（分号分隔）                              │
└──────────────────────┬──────────────────────────────────┘
                       ↓
            ┌──────────────────────┐
            │  语句1: select ...   │ → 压栈 → 注入 @sybn_last_select@table
            └──────────┬───────────┘      （source: 消费0 压栈1）
                       ↓
            ┌──────────────────────┐
            │  语句2: 转换命令      │ → 弹栈1个处理 → 压栈 → 注入 @sybn_last_conver@table
            │  (appendColumns等)   │      （convert: 消费1 压栈1）
            └──────────┬───────────┘
                       ↓
            ┌──────────────────────┐
            │  语句3: join          │ → 弹栈2个(左+右) → join → 压栈 → 注入 @sybn_last_join@table
            │  (left join 等)      │      （multi-input: 消费2 压栈1）
            └──────────┬───────────┘
                       ↓
            ┌──────────────────────┐
            │  语句4: 子查询命令    │ → 执行子SQL → 压栈
            │  (execBatch等)       │      （source: 消费0/1 压栈1）
            └──────────┬───────────┘
                       ↓
            ┌──────────────────────┐
            │  语句N: return        │ → 指定返回栈中某层
            └──────────┬───────────┘      （control-flow: 不消费不压栈）
                       ↓
                 返回最终结果

五、nl2sql 命令选择指南

自然语言转 SQL 时，按用户意图映射命令：

六、相关文档

命令详解

• 列操作命令（align/append/prepend/remove/split）
• builderInsert
• clearQueue
• peekResult
• return
• explain
• unnest / unwind
• 后置 where/order/limit
• execBatch
• dynamicSourceQuery
• cacheResult
• pivot
• if exists
• fill
• join / lookup（多输入转换）

内联数据源

• from factory（factory/generate_series）
• web-sql part2（from JSON 数组）
• 源码：sybn-core/src/main/java/cn/sybn/util/io/db/common/helper/loader/TableLoader.java — from 字面量数据源加载（JSON/CSV/TSV/VALUES/factory/generate_series）

基础规范

• SQL 标准支持
• 在线测试
• 变量机制
• 函数列表