WrenAI Wren Core 语义核心模块解析：基于 DataFusion 的 MDL 语义层与 SQL 规划引擎
发布时间：2026/9/13 20:26:21 作者：尧图编辑部 阅读量：1,286
WrenAI Wren Core 语义核心模块解析基于 DataFusion 的 MDL 语义层与 SQL 规划引擎【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI导读core/wren-core/是 WrenAI 中 Wren Engine 的语义核心Semantic Core一个基于 Apache DataFusion 构建的 Rust 语义层它接收一份MDLModeling Definition Language建模定义语言清单与一条 SQL 查询通过语义层完成模型Model、关系Relationship、度量Metric与视图View的解析、行级/列级访问控制RLAC/CLAC的施加以及逻辑计划的优化最终输出改写后的可执行 SQL。本文以 core/wren-core/README.md 为骨架结合该模块源码、sqllogictest 测试与基准测试工程完整讲解它的职责边界、测试/构建方式与编码规范帮助你理解 WrenAI 中自然语言 → 可信 SQL链路里最底层的语义规划环节。一、Wren Core 在 WrenAI 中的定位根据 README 的定位说明Wren Core 模块是 Wren Engine 的语义核心它被ibis-server 的 API v3用于 SQL 规划SQL planning除了 Rust 库本身还存在一套 Python 绑定模块 core/wren-core-py同样服务于 ibis-server语义层依赖 MDLModeling Definition Language来描述数据集这也是 WrenAI 中开放上下文层open context layer的核心载体。从仓库结构看core/wren-core是一个包含四个 crate 的 Cargo workspace见 core/wren-core/Cargo.tomlCrate作用core/主库wren-semantic-corelib 名为wren_coreMDL 处理、分析器规则、优化器 pass、SQL 生成sqllogictest/基于.slt文件的 SQL 端到端测试benchmarks/性能基准测试TPC-H 与 Wren 专属复杂查询wren-example/使用示例plan-sql、view、row-level-access-control 等core/目录下 crate 的描述core/wren-core/core/Cargo.toml明确指出其定位Wren semantic engine — MDL-based semantic SQL layer and query planner built on Apache DataFusion依赖 DataFusion v53、wren-core-base共享的 Manifest 类型定义等。核心入口 core/wren-core/core/src/lib.rs 只导出两个模块logical_plan与mdl并对外暴露AnalyzedWrenMDL与WrenError可见其公共 API 面刻意收敛在MDL 分析 逻辑计划两个维度。从源码结构看wren-core 与 core/wren-core-base 的分工是wren-core-base 承载 Manifest、Builder、数据源枚举等共享类型该模块同时被 wren-core-py 复用而 wren-core 负责将这些类型激活成可规划的语义引擎。二、核心能力从 MDL 清单到改写后的 SQL2.1 核心数据结构AnalyzedWrenMDL与WrenMDL语义引擎的中心结构在 core/wren-core/core/src/mdl/mod.rsWrenMDL持有ManifestMDL 清单、qualified_references限定列名 → 列引用符号表、register_tables已注册的表提供者与catalog_schema_prefixAnalyzedWrenMDL由WrenMDLLineage血缘构成是整个分析结果的聚合体Default实现会构建一个空清单的实例。AnalyzedWrenMDL提供三种分析入口对应不同的数据源接入场景analyze(manifest, properties, mode)根据Mode如Unparse/PermissionAnalyze注册远程表见下并构建血缘同时执行validate_clac_rule做列级访问控制校验analyze_with_tables(manifest, register_tables)直接注入一组TableProvider如来自 wren-core-py 的 Python 侧表适合外部运行时已持有表句柄的场景analyze_with_url_tables(manifest, ctx)面向文件型数据源LocalFile / MinioFile / S3File / GcsFile将模型tableReference当作 URL 解析为 ParquetListingTable。该方法注释特别说明它遵循 DuckDB-WASM 模式——已知 URL 已知格式.parquet因此跳过DynamicListTableFactory所需的 WebDAV PROPFIND 列表探测只用 GET Range 读取 Parquet footer 做 schema 推断。2.2transform_sql语义层 SQL 改写主流程README 说该模块utilized by the API v3 of the ibis-server for SQL planning落到代码上即 mdl/mod.rs 中的transform_sql/transform_sql_with_ctx注册远程函数将RemoteFunction标量/聚合/窗口以ByPassScalarUDF等方式注册进 DataFusion 的SessionContext。这里有个关键细节DataFusion 在 SQL 解析时会规范化函数名为小写因此代码同时注册原始名与小写别名保证 SQL 生成时能还原函数原名应用语义上下文apply_wren_on_ctx把 MDL 施加到会话上Mode::Unparse表示当前处于反解析生成 SQL模式创建并优化逻辑计划create_logical_plan→optimize期间ModelAnalyzeRule会把TableScan改写为ModelPlanNodecore/wren-core/core/src/logical_plan/analyze/plan.rs再展开关系链、计算字段、视图反解析回 SQL使用WrenDialect按数据源选择方言配合Unparser通过扩展的SqlReferenceNodeUnparser输出格式化 SQL并去掉 MDL 自带 catalog/schema 前缀。transform_sql是同步封装依赖multi-threadfeature 下的 tokio 多线程运行时transform_sql_with_ctx是异步版本WASM 场景必须走异步路径。create_wren_ctx同文件会按数据源注册对应的标量/聚合/窗口函数并将默认时区设为 UTC 以避免 timestamp 推断问题同时允许用户配置覆盖。2.3 权限分析与友好报错permission_analyzemdl/mod.rs实现了一个巧妙的兜底逻辑正常执行流中未被允许的列不会注册进WrenDataSource于是越权查询会表现为column not found。此时引擎用Mode::PermissionAnalyze重新分析若发现底层错误是WrenError::PermissionDenied定义于 core/wren-core/core/src/logical_plan/error.rs则把原始错误替换为更友好的权限拒绝信息。三、测试与构建cargo test与 sqllogictest3.1 运行全部测试README 给出唯一的全量测试命令cargo test并说明测试分布单元测试绝大多数位于src/mdl/mod.rsworkspace 下即core/src/mdl/mod.rs。该文件内嵌的测试覆盖了带别名模型扫描aliased model scan只构建一次ModelPlanNode、join 两侧别名模型的改写、count(*)、远程函数add_two、median、大小写敏感的 catalog/schema、通过insta快照断言改写结果等场景SQL 端到端测试使用sqllogictests执行即 core/wren-core/sqllogictest crate。workspace 配置core/wren-core/Cargo.toml要求 Rust 1.78edition 2021。corecrate 的默认 feature 为multi-threadcore/wren-core/core/Cargo.toml启用 tokio 多线程运行时以支撑同步transform_sqlWASM 构建需关闭该 feature 走单线程异步。3.2 sqllogictestSQL 端到端测试详解sqllogictest cratecore/wren-core/sqllogictest/Cargo.toml基于sqllogictest 0.28.4测试二进制为bin/sqllogictests.rs测试文件位于test_files/tpch/tpch.slt 22 个q*.slt.part将 TPC-H 的 22 条查询作为语义层改写与执行验证model.slt/type.slt/view.slt分别覆盖模型访问、类型处理与视图展开引擎实现src/engine/在 DataFusion 之上提供转换conversion、结果规范化normalize与输出格式化output并对类型列做严格校验strict_column_validator。与源码分析相互印证的是AGENTS.md 指向的模块说明.claude/CLAUDE.md记录了已知限制ModelAnalyzeRule目前无法解析相关子查询correlated subquery中的外层列引用影响 TPC-H Q2、Q4、Q15、Q17、Q20、Q21、Q22——这正是仓库保留tpch.slt作为回归基准的原因之一。3.3 基准测试可选延伸workspace 还包含benchmarks/cratecore/wren-core/benchmarks/README.md提供两套基准标准 TPC-H 2.17.122 条决策支持查询与 Wren 专属复杂查询q1多 CTE 子查询、q2额外含UNION。快速运行方式./bench.sh # 查看用法 ./bench.sh run tpch # 收集基准数据 ./bench.sh compare main mybranch # 分支间对比compare.py会输出逐查询耗时对比与汇总表总耗时/平均耗时/快慢统计。更精细的控制可用cargo run --release --bin tpch -- benchmark --query 1 -i 10 -o result.json直接调用常用参数--query、-i/--iterations、-o/--output、--all-queries。注意本文不把基准测试数据当作性能结论引用它仅用于验证语义层改写与优化是否引入回归。四、编码规范rustfmt 与 taploREADME 明确要求提交 PR 前保证代码格式正确规则简单清晰4.1 Rust 代码cargo fmtcargo fmt全 workspace 格式化可加--allcargo fmt --all。同时 lint 建议使用cargo clippy --all-targets --all-features -- -D warnings见.claude/CLAUDE.md的开发命令。4.2 TOML 文件taplo先安装taplo-cli再执行格式化cargo install taplo-cli --locked taplo fmt仓库根目录的 core/wren-core/taplo.toml 是 taplo 的配置。注意 workspace 下还有 core/wren-core/rustfmt.toml 统一控制 Rust 格式。完整开发命令清单来自模块说明文件cargo check --all-targets # 编译检查 RUST_MIN_STACK8388608 cargo test --lib --tests --bins # 运行测试加大栈空间 cargo fmt --all # 格式化 cargo clippy --all-targets --all-features -- -D warnings # Lint taplo fmt # 格式化 TOML五、相关工程资源与延伸阅读模块说明与架构约定core/wren-core/AGENTS.md指向.claude/CLAUDE.md查看更多构建命令与已知限制主库 crate 说明安装与使用方式core/wren-core/core/README.md —— 发布名为wren-semantic-core库内以wren_core导入依赖声明示例wren-semantic-core 0.1主要能力包括 MDL 分析、查询规划关系链解析与视图展开、RLAC/CLAC 访问控制、类型强制与时间戳简化等优化 passMDL 清单样例测试用core/wren-core/core/tests/data/mdl.json 展示了catalog/schema/models含tableReference、列、计算字段expressionisCalculated、关系列relationship、primaryKey的完整结构优化 passsimplify_timestamp与type_coercion位于 core/wren-core/core/src/logical_plan/optimize分析规则access_controlRLAC/CLAC、expand_view、model_anlayze、model_generation、plan 位于 core/wren-core/core/src/logical_plan/analyzePython 绑定core/wren-core-py/同为 ibis-server 所用运行示例wren-example/下提供了plan-sql.rs、view.rs、row-level-access-control.rs等可直接参考的用法结语core/wren-core是 WrenAI 语义层的 Rust 实现核心它以 MDL 清单为输入依托 DataFusion 完成语义 SQL → 逻辑计划 → 优化 → 方言化 SQL的完整闭环并将访问控制、远程函数、血缘与多数据源方言等能力收敛为精简的公开 APIAnalyzedWrenMDL、transform_sql。阅读本文后你应当能够理解该模块在 ibis-server 中的定位与三种分析入口掌握cargo test与 sqllogictest 的测试体系以及遵循 rustfmt/taplo 规范参与贡献。【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 