目前这个项目已经不只是一个 parser。它包含 scanner、parser、AST dump、表达式解释器、运行时值模型、标准库 package、表流执行、SQLite/MySQL connector、查询计划、Page-based physical executor、CLI、REPL、LSP 和 conformance examples。换句话说，它已经有了一个小型语言运行时和单机查询引擎的骨架。

为什么选择 Flux

Flux 的语法很适合拿来做查询引擎实验。它既有脚本语言的表达能力，也有面向数据流的 pipeline 模型：

import "array"

array.from(rows: [
    {_time: 2024-01-01T00:00:00Z, host: "edge-1", region: "east", usage: 91},
    {_time: 2024-01-01T00:01:00Z, host: "edge-2", region: "west", usage: 42},
])
    |> filter(fn: (r) => r.usage > 80)
    |> keep(columns: ["host", "usage"])
    |> yield(name: "hot_hosts")

这段代码同时覆盖了几个关键点：导入 package、构造内存表、使用 record、使用 lambda、高阶函数、pipe-forward、表变换和结果输出。为了让它真正跑起来，项目至少需要完成词法分析、语法分析、AST 表达、作用域、函数调用、运行时值、表模型、builtin 注册和输出格式化。

Scanner：把字符流切成 token

Flux 的词法并不只是普通标识符和数字。当前 scanner 覆盖了关键字、字符串、字符串插值、duration、RFC3339 风格 datetime、正则字面量、注释、pipe-forward、比较运算符、属性注解和类型语法相关 token。

正则字面量是一个典型细节。/cpu.*/ 和除法操作符都以 / 开头，scanner 不能只靠单个字符判断。当前实现区分表达式上下文，在可能期待表达式的位置接受 regex literal，在普通二元运算位置按除法处理。这类细节决定了 parser 后面看到的 token 是否有语义。

scanner 还维护 line/column 信息。这个成本看起来不大，但收益很高：parser error、AST dump、LSP diagnostics、goto definition、semantic tokens 都需要准确的 source location。

Token 设计里几个容易低估的点

第一个点是 import、option、builtin、testcase 这些关键字不是普通标识符。它们在文件级语法和语句级语法里有特殊入口，如果 scanner 不提前分类，parser 就必须在更多地方做字符串判断。

第二个点是 duration 和 unsigned integer。1h、5m、42u 看起来像数字加后缀，但语义完全不同。duration 后续要参与 time range/window 计算；unsigned integer 则进入普通 numeric value。scanner 和 parser 必须在 AST 层把它们分开。

第三个点是字符串插值。"host ${user}" 不是普通字符串拼接，parser 需要保留插值表达式，这样 runtime 才能在当前 environment 下求值。

Value：运行时的统一数据模型

解释器首先需要一个统一的运行时值类型。当前 Value 覆盖了 Flux 子集执行所需的主要类型：

• null
• bool
• int / uint / float
• string
• time
• duration
• regexp
• array
• object
• function
• table

数组和对象是很多高级能力的基础。数组承载 array.map/filter/reduce 这类高阶函数；对象既表示普通 record，也表示 package object、函数命名参数和 table row。

table 是项目中特别重要的一类值。它不是单张二维表的简单包装，而是 Flux table stream 的内存表示，包含 rows、logical tables、group key、bucket、result name 等信息。后续查询执行文章会单独展开。

Value 的工程取舍

Value 是解释器最核心的数据结构之一。它需要在两个方向之间取平衡：一方面要足够通用，能承载 Flux 的动态值；另一方面不能变成“什么都能塞”的无约束容器。

当前实现把类型枚举和具体 payload 绑定在一起，调用方通过 type() 判断，再使用 as_int()、as_array()、as_object() 这类访问器取值。这种设计比到处使用 std::any 更可控，也比一开始引入复杂类型系统更轻量。

它的代价是 runtime 需要大量显式类型检查。例如 builtin 取参数时必须确认字段存在、类型正确、数组元素符合预期。项目里很多 helper 的价值就在这里：把重复的参数检查、错误信息和 StatusOr 返回模式收敛起来，避免每个 builtin 都手写一套脆弱逻辑。

当前支持的函数形态

当前实现支持 expression-bodied function：

double = (x) => x * 2

也支持 block-bodied function：

其中 array 最适合用来讲 builtin 扩展机制，因为它既有普通函数，也有高阶函数，还和“如何替代传统循环”这个问题直接相关。

Package import 如何工作

用户写：

import "array"

运行时会从 BuiltinRegistry 中加载 package object，并在当前环境中绑定 array。之后：

这篇文章专门讲 cpp/pl/flux 里 table pipeline 的内存执行模型。它是早期 eager interpreter 的核心，也是 connector / physical executor fallback 到 materialized output 时的共同承载格式。理解这一层，后面的 connector pushdown、logical/physical plan 和性能优化才有上下文。

一个贯穿全文的查询

先看一个 dashboard 查询。它从 CSV 读入 CPU 数据，按时间过滤，再按主机分组，最后做窗口聚合：

import "csv"

csv.from(file: "cpp/pl/flux/examples/ops_dashboard/data/cpu_usage.annotated.csv")
    |> range(start: 2024-01-01T00:00:00Z, stop: 2024-01-01T00:05:00Z)
    |> filter(fn: (r) => r.region == "us-west")
    |> group(columns: ["host"])
    |> aggregateWindow(every: 1m, fn: mean, createEmpty: true)

从用户角度看，这是一条线性的 pipe。从执行器角度看，每一步都在转换一个 table stream：输入可能包含多张 logical table，输出也可能包含多张 logical table，并且每张表都有自己的 group key、列集合和行集合。

如果还沿用最朴素的解释器思路，sqlite.from() 先把整张表读成 TableValue，再让 range、filter、keep、sort 在内存里慢慢跑，那么这个实现虽然容易写，却很难称为查询引擎。真正有意义的边界是：Flux 仍然是统一查询语言，但能够把安全、明确、可证明等价的一段计划下推到数据源附近执行。

这一篇就专门讲 cpp/pl/flux 当前的 connector 与 pushdown 设计。它不是“把 Flux 翻译成任意 SQL”，而是一套更保守的执行模型：provider package 负责建立数据源入口，optimizer 识别可下推前缀，connector runtime 按 metadata、split、page source 三层执行，unsupported suffix 则可靠 fallback 回内存执行器。

先看一条典型查询：

import "sqlite"

sqlite.from(path: "metrics.db", table: "cpu")
    |> range(start: 2024-01-01T00:00:00Z, stop: 2024-01-01T01:00:00Z)
    |> filter(fn: (r) => r.host == "edge-1" and r._value > 80.0)
    |> keep(columns: ["_time", "host", "_value"])
    |> sort(columns: ["_time"])
    |> limit(n: 10)

从用户视角看，这就是一条普通 Flux pipeline。从引擎内部看，它可以被拆成两段：前缀部分能变成 SQL SELECT ... WHERE ... ORDER BY ... LIMIT ...，后缀部分如果还有复杂 Flux 算子，则继续由内存 runtime 接管。这个“能不能下推”的判断，就是本文的核心。

如果项目只有 eager interpreter，执行路径很直接：AST 调 builtin，builtin 操作 TableValue，然后把结果传给下一个 builtin。但 connector、pushdown、多 split、exchange、partial/final aggregate 和 profile 加进来后，直接解释 AST 就不够了。执行器必须先有一个“尚未执行、可以改写、可以解释”的查询表示。

这就是 logical/physical plan 的位置。Logical plan 负责保存用户查询语义，optimizer 负责改写语义等价的计划，physical plan 负责描述执行拓扑，scheduler 再把它变成 driver 和 operator。

一个贯穿全文的查询

先用一条查询做主线：

import "sqlite"

sqlite.from(path: "metrics.db", table: "cpu")
    |> range(start: 2024-01-01T00:00:00Z, stop: 2024-01-01T01:00:00Z)
    |> filter(fn: (r) => r.host == "edge-1" and r._value > 80.0)
    |> keep(columns: ["_time", "host", "_value"])
    |> group(columns: ["host"])
    |> mean(column: "_value")
    |> sort(columns: ["_value"], desc: true)
    |> limit(n: 10)

这条查询里同时有 source scan、时间范围、谓词、projection、group aggregate、sort 和 limit。它足够小，但已经覆盖了查询引擎里最核心的几个问题：

cpp/pl/flux/contrib/lsp 的目标就是让 Flux 从“能执行”走到“能日常编辑”：打开文件时能诊断语法错误，输入 array. 时能补 package 函数，光标放在 lambda 参数上能跳回定义，rename 不会误改 shadowing 变量，semantic tokens 能区分 package、函数、参数和引用。

这一篇不按功能列表平铺，而是从一次编辑器请求开始，看 Flux Language Server 如何把 JSON-RPC、文档同步、AST 缓存、符号表和各类 feature handler 串起来。

一次编辑器请求如何流动

假设用户在编辑器里打开了这样一段 Flux：

import "array"

data = array.from(rows: [{host: "edge-1", usage: 91.2}])

data
    |> filter(fn: (r) => r.usage > 80.0)
    |> keep(columns: ["host", "usage"])

当用户输入 array.、保存文件、或者把光标放到 r.usage 上时，编辑器会通过 LSP 向 server 发请求或通知。server 不能每个功能都自己 parse 一遍，也不能把 completion、diagnostics、definition 写成彼此独立的临时逻辑。它需要一套共享的语言服务基础设施。

cpp/pl/flux 现在已经有 scanner/parser、runtime evaluator、标准库、table pipeline、connector、optimizer、physical executor、CLI 和 LSP。它不是一个单点库，而是一条从源码到编辑器、从 AST 到查询执行、从语义到性能的链路。测试体系要守住的不是某个函数，而是这条链路的边界。

这一篇讲的不是“多写测试”这种泛泛建议，而是 Flux 项目当前如何分层：哪些 bug 应该落在 parser test，哪些应该落在 runtime eval，哪些必须进入 conformance，哪些只能靠 benchmark 观察趋势。

测试不是一类

当前测试大致分成这些层：

• scanner / strconv unit test。
• parser unit test 和 AST dump。
• runtime value/env/eval/page/exec unit test。
• connector runtime/source unit test。
• optimizer RBO/CBO unit test。
• CLI unit/smoke test。
• stdlib conformance test。
• cross-source 和 feature examples。
• LSP unit test。
• benchmark runner。
• 静态检查。

每一层守不同边界。parser test 不应该承担 runtime 正确性；runtime eval test 不应该依赖真实 MySQL；LSP test 不应该通过人工打开编辑器来证明 JSON-RPC 正确；benchmark 更不应该伪装成 correctness test。