在 .NET 中使用 prql-net：PRQL 编译器官方 .NET 绑定入门指南

后端【免费下载链接】prqlPRQL is a modern language for transforming data — a simple, powerful, pipelined SQL replacement项目地址https://gitcode.com/gh_mirrors/pr/prql点击查看免费下载PRQLPipelined Relational Query Language是一种面向数据转换的现代语言定位为“简单、强大、管道化的 SQL 替代品”。prql-net是 PRQL 官方为 .NET 生态提供的语言绑定库通过静态类PrqlCompiler将 PRQL 查询编译为 SQL并暴露了从 PRQL 到 PL AST、RQ AST 再到 SQL 的分阶段编译能力。读完本文你将掌握如何在net10.0项目中安装原生依赖、调用Compile一行完成 PRQL→SQL 编译并理解Result/Message错误模型、分阶段 API 及底层 FFI 调用链。项目概况与版本状态prql-net位于仓库的 prqlc/bindings/dotnet 目录对应说明文档为 prqlc/bindings/dotnet/README.md。它提供的是net10.0目标框架的库见 PrqlCompiler.csproj 中的TargetFrameworknet10.0/TargetFramework。当前该绑定仍处于早期阶段版本 0.1.0尚未发布到 NuGet需要直接从源码构建使用官方欢迎社区贡献。之所以停留在 0.1.0是因为项目正在等待prqlc-cC ABI 层更新到最新 API届时版本号将随 PRQL 主版本同步。绑定层的公共 API 只有一个静态类PrqlCompiler其Compile、PrqlToPl、PlToRq、RqToSql四个方法均返回携带编译产物字符串Output与诊断消息集合Messages的Result对象。核心实现位于 PrqlCompiler.cs类型定义集中在 PrqlCompiler 目录下。安装与原生库放置prql-net并非纯托管实现——真正的编译器逻辑由 Rust 编写的prqlc提供.NET 绑定通过 P/Invoke 动态调用 C ABI 层的libprqlc_c原生库。因此安装分两步构建或获取原生库libprqlc_c的 Rust 源码位于 prqlc/bindings/prqlc-c/src/lib.rs需按平台编译为对应动态库文件Linuxlibprqlc_c.somacOSlibprqlc_c.dylibWindowslibprqlc_c.dll把原生库放进输出目录确保libprqlc_c与PrqlCompiler.dll及其他编译产物位于同一目录即{your_project}/bin/Debug/net10.0/。libprqlc_c是在运行时被动态导入的而不是编译期链接。从工程配置看库项目本身已在 PrqlCompiler.csproj 中为三种平台的libprqlc_c声明了CopyToOutputDirectoryPreserveNewest/CopyToOutputDirectory只要这些文件存在于项目目录构建时就会自动复制到输出目录。在使用方项目中你需要参照上述约定自行放置或配置复制原生库。快速开始编译第一条 PRQL 查询在项目中引入Prql.Compiler命名空间后即可通过静态方法直接编译using Prql.Compiler; var options new PrqlCompilerOptions { Format false, SignatureComment false, }; var result PrqlCompiler.Compile(from employees, options); Console.WriteLine(result.Output);这里Format false表示不美化生成的 SQL否则会多行缩进排版SignatureComment false表示不在 SQL 末尾附加编译器签名注释。该示例与测试 CompilerTest.cs 中ToCompile_Works用例的断言一致from employees在指定Target sql.mssql时输出为SELECT * FROM employees。PrqlCompilerOptions编译选项详解所有 SQL 后端编译选项都封装在 PrqlCompilerOptions.cs 中它是一个sealed record支持init初始化器属性类型默认值说明Formatbooltrue是否将生成的 SQL 通过格式化器拆分为多行并美化缩进与空格Targetstring?null编译目标与方言例如sql.mssql、sql.duckdb等为null时走默认方言SignatureCommentbooltrue是否在生成的 SQL 末尾附加编译器签名注释这些选项与 Rust 侧 C ABI 的Options结构体一一对应。查看 prqlc/bindings/prqlc-c/src/lib.rs 可以发现原生Options包含format、target、signature_comment三个字段且注释明确说明target默认为sql.any——即从查询头query header中的target参数确定 SQL 方言。托管侧 NativePrqlCompilerOptions.cs 通过[StructLayout(LayoutKind.Sequential)]定义了与原生结构体内存布局一致的对应结构bool折叠为byteTarget字符串通过Marshal.StringToCoTaskMemUTF8转为IntPtr指针传递。在 PrqlCompiler.cs 的Compile实现中可以看到完整生命周期先为Target分配非托管内存构造原生选项结构体调用CompileExtern后在finally块中通过Marshal.FreeCoTaskMem释放指针避免内存泄漏。Result 与 Message错误处理模型与大多数“编译失败即抛异常”的绑定不同prql-net采用结果对象模型编译错误不会作为异常抛出而是记录在Result.Messages中。只有参数本身的非法情况空字符串、null选项才会抛出ArgumentException/ArgumentNullException。Result 结构Result.cs 定义了两个公共成员string Output编译产物SQL 字符串或中间阶段产生的 JSONIReadOnlyCollectionMessage Messages错误、警告与 lint 消息集合。Result的内部构造函数接收原生NativeResult含Output指针、Messages数组指针与MessagesLen长度逐条解析消息并在finally中调用result_destroy对应原生result_destroy入口释放由 Rust 侧分配的内存。Message 字段Message.cs 中的每个诊断消息包含字段类型说明KindMessageKind消息类型见下文枚举Codestring?机器可读的错误标识符可为nullReasonstring错误纯文本Hintstring?修复建议可为nullSpanSpan?错误在源文件中的字符偏移区间Start/End可为nullDisplaystring?带原因与提示的代码标注文本可为nullLocationSourceLocation?源文件中的行列区间StartLine/StartCol/EndLine/EndCol可为nullMessageKind见 MessageKind.cs目前定义了Error、Warning、Lint三种枚举值虽然注释说明当前仅有Error被实际实现。Span与SourceLocation均为readonly record struct分别定义在 Span.cs 与 SourceLocation.cs。测试 CompilerTest.cs 中的Compile_ReportsErrorMessages用例验证了错误路径对from employees | unknown_function col编译后Messages非空首条消息的Kind为ErrorReason、Span、Location、Display均被填充。这意味着你可以在 UI 或日志中直接使用Location定位出错行列、用Display展示带上下文的源码标注。分阶段编译PrqlToPl → PlToRq → RqToSql除了一步到位的CompilePrqlCompiler还暴露了 PRQL 编译管线的三个阶段每个阶段返回 JSON 形式的中间产物对应 prqlc Rust crate 中prql_to_pl、pl_to_rq、rq_to_sql三个函数方法输入输出PrqlToPl(string prqlQuery)PRQL 源码PL ASTJSONPlToRq(string plJson)PL AST JSONRQ ASTJSONRqToSql(string rqJson, PrqlCompilerOptions options)RQ AST JSONSQL 字符串各阶段职责在原生的 prqlc/bindings/prqlc-c/src/lib.rs 注释中有明确说明pl_to_rq会“查找变量引用、校验函数调用、确定 frame帧并将 PL 转换为 RQ”。这条管线对需要做自定义分析、AST 改写或跨阶段调试的开发者很有价值。值得注意的实现细节原生compile函数本身正是prql_to_pl、pl_to_rq、rq_to_sql三者串联的包装见 lib.rs只是省去了每步之间的 JSON 序列化。测试TestOtherFunctions验证了这一等价性对同一查询走PrqlToPl → PlToRq → RqToSql管线与直接Compile得到完全一致的Output与Messages。示例先定义一个let变量再引用它var query let a (from employees | take 10) from a | select {first_name} ; var options new PrqlCompilerOptions(); var pl PrqlCompiler.PrqlToPl(query); // PL AST JSON var rq PrqlCompiler.PlToRq(pl.Output); // RQ AST JSON var sql PrqlCompiler.RqToSql(rq.Output, options); // SQL底层 FFI 与 UTF-8 编组从 PrqlCompiler.cs 可以看到四个公开方法分别对应四个[LibraryImport]声明的 P/Invoke 入口compile、prql_to_pl、pl_to_rq、rq_to_sql统一使用StringMarshalling.Utf8编组字符串。这一点对中文等非 ASCII 输入尤为重要。测试Compile_HandlesNonAsciiInput专门守护了这一路径默认的 ANSI 编组会静默破坏非 ASCII 字节而LibraryImportStringMarshalling.Utf8能正确往返from employees | filter name Café这类查询编译结果中仍保留Café。因此在使用本绑定时请确保项目启用了LibraryImport.NET 7 的源生成 P/Invoke不要退化为传统的 ANSIDllImport。同时Result的构造过程通过Marshal.PtrToStructure按NativeMessage顺序布局解析每个消息元素并使用手动字节扫描将 UTF-8 指针转换为托管字符串见 Result.cs配合result_destroy保证原生内存正确回收。参数校验与异常约定PrqlCompiler的公开方法遵循严格的参数校验约定由测试 CompilerTest.cs 逐项验证查询或 JSON 输入为null或空字符串时抛出ArgumentException且ParamName精确指向对应参数如prqlQuery、plJson、rqJson测试Compile_ThrowsArgumentException_WhenQueryIsEmpty是一个针对旧实现曾把参数名误放入 message 槽位的回归测试options为null时抛出ArgumentNullExceptionCompile_ThrowsArgumentNullException_WhenOptionsNull、RqToSql_ThrowsArgumentNullException_WhenOptionsNull。也就是说使用时应以“查询本身是否合法”与“参数是否合法”两个维度区分错误处理前者看result.Messages后者靠异常。应用场景与后续路线prql-net适合以下 .NET 场景在 C# 服务端将 PRQL 查询字符串实时编译为 SQL 后下发给数据库执行基于PrqlToPl/PlToRq做查询分析、审计或自定义优化结合Target参数为不同数据库方言如sql.mssql、sql.duckdb生成对应 SQL。需要注意的是该绑定仍处早期阶段0.1.0尚未发布 NuGet 包随着prqlc-c更新到最新 API版本号会与 PRQL 主版本对齐。阅读更深入的中间表示PL/RQ与目标方言说明可继续浏览本仓库的 prqlc/prqlc 核心实现以及各阶段对应的测试 CompilerTest.cs。若想了解 PRQL 语言本身的语法from、select、filter、let等可以参考仓库 web/book/src 下的语言文档。赞分享后端【免费下载链接】prqlPRQL is a modern language for transforming data — a simple, powerful, pipelined SQL replacement项目地址https://gitcode.com/gh_mirrors/pr/prql点击查看免费下载相关推荐TensorFlowSharp入门指南在.NET中使用TensorFlowTensorFlowSharp入门指南在.NET中使用TensorFlow 概述 TensorFlowSharp是一个强大的.NET绑定库它允许开发者在C人工智能机器学习深度学习TensorFlowSharp入门指南在.NET中使用TensorFlowTensorFlowSharp入门指南在.NET中使用TensorFlow TensorFlowSharp是一个强大的.NET API它允许开发者在C 和F人工智能机器学习深度学习在 JVM 中使用 prql-javaPRQL 编译器 JNI 绑定的安装、配置与源码剖析在 JVM 中使用 prql javaPRQL 编译器 JNI 绑定的安装、配置与源码剖析 导读 prql java 是 PRQL 项目官方提供的 Java后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考