PRQL 编译器 prqlc 实战指南：从 CLI 管道编译到 Rust 库集成

PRQL 编译器 prqlc 实战指南从 CLI 管道编译到 Rust 库集成【免费下载链接】prqlPRQL is a modern language for transforming data — a simple, powerful, pipelined SQL replacement项目地址: https://gitcode.com/gh_mirrors/pr/prqlprqlc是 PRQLPipelined Relational Query Language的官方参考编译器实现用 Rust 编写既是一个把 PRQL 编译为 SQL 的库也是一个独立的命令行工具。本文以 prqlc/prqlc/README.md 为核心结合仓库源码与集成测试系统讲解prqlc的安装、CLI 用法、编译目标与方言、Shell 补全以及如何将其作为 Rust 库嵌入你的项目并深入编译流水线的内部结构。prqlc 是什么PRQL 的参考编译器与 CLIPRQL 是一种面向数据转换的现代查询语言定位为简单、强大、管道式的 SQL 替代品。prqlcPRQL Compiler 的缩写就是这门语言的参考实现它将 PRQL 源码解析、语义分析并最终生成 SQL同时对外提供两层能力CLI一个单一、无运行时依赖dependency-free的可执行文件从 stdin 或文件中读取 PRQL向 stdout 输出 SQLRust 库暴露compile等 API 与Options配置结构供其他 Rust 程序在运行时或构建时调用。从仓库结构看prqlc由多个 crate 协作而成prqlc/prqlc-parser负责词法与语法解析prqlc/prqlc是主编译器与 CLI 入口prqlc/prqlc-macros提供编译期宏prqlc/bindings下还衍生出了 Python、JavaScript、Java、.NET、PHP、Elixir 等语言绑定。本文聚焦于 Rust 生态内的prqlc本体与 CLI。快速上手用prqlc compile把 PRQL 变成 SQLprqlc compile是一个过滤器filter式命令从标准输入读入 PRQL 字符串向标准输出写出 SQL 字符串。$ echo from employees | filter has_dog | select salary | prqlc compile SELECT salary FROM employees WHERE has_dog这段 PRQL 表达的是从 employees 表中取出 has_dog 为真的行再选择 salary 列对应 SQL 的SELECT salary FROM employees WHERE has_dog。PRQL 的管道风格from→filter→select让变换顺序与人类思考顺序一致。注意默认输出是格式化过的多行 SQL。若需要紧凑的单行 SQL可加--no-format参数对应源码中Options.format为 false 的分支。交互模式无参数启动 REPL执行prqlc compile而不传任何参数时会进入交互模式允许逐行书写 PRQL。写完查询后在 Linux、macOS 上按Ctrl-d、在 Windows 上按Ctrl-z提交即可显示编译后的 SQLprqlc compile源码层面这一行为由 cli/mod.rs 实现当输入路径为-且标准输入是终端TTY时程序会打印提示语 Enter PRQL, then press ctrl-d to compile: 然后等待用户输入。与 DuckDB CLI 组合PRQL 直接驱动数据库查询prqlc编译出的 SQL 可以交给任何兼容 SQL 的 CLI 工具执行例如 DuckDB CLI。仓库 README 给出了一条完整的实战链路先把 Chinook 示例数据集albums.csv下载到本地再用 PRQL 查询并直接管道给 duckdb$ echo from albums.csv | take 3 | prqlc compile | duckdb ┌──────────┬───────────────────────────────────────┬───────────┐ │ album_id │ title │ artist_id │ │ int64 │ varchar │ int64 │ ├──────────┼───────────────────────────────────────┼───────────┤ │ 1 │ For Those About To Rock We Salute You │ 1 │ │ 2 │ Balls to the Wall │ 2 │ │ 3 │ Restless and Wild │ 2 │ └──────────┴───────────────────────────────────────┴───────────┘这里用反引号把albums.csv当作表名PRQL 中引用文件路径或含特殊字符的标识符需要反引号take 3等价于 SQL 的LIMIT 3。交互模式同样可以接入$ prqlc compile | duckdb Enter PRQL, then press ctrl-d to compile: from albums.csv take 3 ┌──────────┬───────────────────────────────────────┬───────────┐ │ album_id │ title │ artist_id │ │ int64 │ varchar │ int64 │ ├──────────┼───────────────────────────────────────┼───────────┤ │ 1 │ For Those About To Rock We Salute You │ 1 │ │ 2 │ Balls to the Wall │ 2 │ │ 3 │ Restless and Wild │ 2 │ └──────────┴───────────────────────────────────────┴───────────┘这种PRQL 写查询、管道到执行器的用法让prqlc成为一个可嵌入任何 shell 脚本的查询编译环节。仓库的集成测试数据位于 tests/integration/data/chinook包含多张表的 CSV 与对应 SQL schema可作为本地演练的素材。编译目标与 SQL 方言-t/--target与list-targetsprqlc compile默认生成通用genericSQL但很多数据库方言之间存在语法差异。通过-t或--target参数可以指定目标方言也可通过环境变量PRQLC_TARGET设置# 编译为 PostgreSQL 方言 echo from employees | select {name, age} | prqlc compile -t sql.postgres # 通过环境变量指定 PRQLC_TARGETsql.duckdb prqlc compile query.prql在 cli/mod.rs 中该参数默认值为sql.any并读取PRQLC_TARGET环境变量。使用prqlc list-targets可以列出所有可用的目标名。根据 cli/test.rs 中的快照测试当前支持以下 13 个目标目标名说明sql.any不指定方言从查询头prql target:...提取默认sql.ansiANSI 标准 SQLsql.bigqueryGoogle BigQuerysql.clickhouseClickHousesql.duckdbDuckDBsql.generic通用方言默认后端sql.mssqlMicrosoft SQL Serversql.mysqlMySQLsql.oracleOraclesql.postgresPostgreSQLsql.redshiftAmazon Redshiftsql.sqliteSQLitesql.snowflakeSnowflake从源码看目标解析位于 lib.rs 的Target::from_strsql.any映射为Target::Sql(None)方言从查询头部的prql target:声明提取其余映射到具体的Dialect枚举。而方言的差异处理集中在 sql/dialect.rs每个方言实现一个DialectHandler负责标识符引用符如 MySQL 用反引号、LIMIT/FETCH分页语法、||字符串拼接、日期格式翻译PRQL 使用chronocrate 的 strftime 格式各方言翻译为对应的格式化语法等差异。需要注意支持程度的差别dialect.rs 中的support_level()将 DuckDB、SQLite、Postgres、Redshift、MySQL、Generic、ClickHouse 标记为Supported而 MSSQL、ANSI、BigQuery、Snowflake、Oracle 为Unsupported即测试默认不执行、需要显式标注才会测试。集成测试 tests/integration/queries.rs 据此决定对每个方言运行哪些查询。在 PRQL 查询内部指定目标除了 CLI 参数PRQL 语言本身也支持在查询开头用头部声明目标prql target:sql.postgres from tracks group media_type_id ( sort name take 1 ) join media_types ( media_type_id) select { tracks.track_id, media_types.name }当 CLI 未显式指定--target时这种头部声明生效。上面这段查询在 PostgreSQL 方言下会编译为使用DISTINCT ON的 CTE相关行为在 lib.rs 的回归测试中有快照验证。prqlc compile完整参数解析在 cli/mod.rs 中compile子命令定义如下参数参数/选项说明[INPUT]输入文件或-stdin默认-[OUTPUT]输出文件或-stdout默认-[MAIN_PATH]主管道的标识符多文件项目时指定入口--hide-signature-comment不输出包含 PRQL 版本号的签名注释--no-format输出未格式化、紧凑的 SQL-t, --target TARGET编译目标默认sql.any支持PRQLC_TARGET环境变量--debug-log FILE把编译调试日志写入指定文件支持.json与.html格式--color WHEN颜色输出控制取值auto/always/never默认auto其中--debug-log是排查编译器内部行为的有力工具它会把整个编译过程的日志序列化为 JSON或渲染为 HTML文件扩展名决定输出格式见 cli/mod.rs。--hide-signature-comment对应Options.signature_comment字段——默认生成的 SQL 末尾会带一行类似-- Generated by PRQL compiler version ...的注释。提示compile只编译主管道main pipeline不处理循环loop这是它与更完整的项目级编译的区别。安装 prqlcprqlc支持多种安装途径覆盖主流平台。包管理器HomebrewmacOS、Linuxbrew install prqlcwingetWindowswinget install prqlc预编译二进制项目发布页为 Linux、macOS、Windows 提供预编译二进制适合无法使用上述包管理器的环境。从源码安装需要 Rust 工具链两种方式任选# 从 crates.io 安装 cargo install prqlc# 从本地 PRQL 仓库安装在仓库根目录下执行 cargo install --path prqlc/prqlc安装后验证prqlc --version prqlc --helpprqlc --help输出的命令列表与 cli/test.rs 快照一致包括parse、lex、fmt、collect、debug、experimental、compile、watch、list-targets、shell-completion、help。为常用 Shell 生成补全脚本prqlc shell-completion命令可以为支持的 shell 输出补全脚本把输出保存到对应位置即可让每个会话自动加载。其实现位于 cli/mod.rs基于clap_complete_command生成。BashLinuxprqlc shell-completion bash /etc/bash_completion.d/prqlcmacOSprqlc shell-completion bash /usr/local/etc/bash_completion.d/prqlcfishprqlc shell-completion fish ~/.config/fish/completions/prqlc.fishPowerShellmkdir -Path (Split-Path -Parent $profile) -ErrorAction SilentlyContinue prqlc shell-completion powershell path/to/prqlc.ps1 echo Invoke-Expression -Command path/to/prqlc.ps1 $profilezshprqlc shell-completion zsh ${fpath[1]}/_prqlc并确保~/.zshrc中有以下两行autoload -U compinit compinit -i超越 compile更多 CLI 子命令compile之外prqlc还提供了一系列面向调试、格式化和项目级操作的子命令全部定义在 cli/mod.rs子命令作用parse解析为 PL ASTParser Representation 之后的 Pipelined Language 抽象语法树可输出 YAML 或 JSONlex词法分析输出词法表示Lexer Representation可输出 YAML 或 JSONfmt解析 PRQL 并重新生成规范化的 PRQL 代码PRQL 格式化器collect解析整个项目并把多文件聚合为单一 PRQL 源文件debug annotate解析、解析引用并把每一帧的关系类型以注释形式标注回源码debug lineage输出列级血缘图lineage graph包含 frames、nodes、ast 三部分debug ast打印 AST 数据结构的内存占用信息debug json-schema输出 PL / RQ / Lineage 三种中间表示的 JSON Schemaexperimental doc从 PRQL 模块生成 Markdown 或 HTML 文档experimental highlight对词法 token 做 ANSI 语法高亮watch监听目录把.prql文件自动编译为同名.sql文件lsp启动语言服务器需要lspfeature 构建shell-completion输出 shell 补全脚本fmtPRQL 代码格式化echo from tracks | take 20 | prqlc fmt输出from tracks take 20watch目录级自动编译prqlc watch ./querieswatch会先对目录下的所有.prql文件做一次初始编译然后递归监听文件变更每当.prql文件保存时自动重新编译为同名.sql文件并支持--no-format与--no-signature两个选项见 cli/watch.rs。从 cli/watch.rs 的compile_path可以看出它还内置了 Jinja 预处理/后处理先对 PRQL 做 Jinja 模板展开编译成 SQL 后再把上下文注入回去。单个文件编译失败不会中断整个 watch 循环这正是该工具用于迭代式开发的定位对应 cli/watch.rs 中的测试。debug lineage列级血缘分析echo from tracks | select {artist, album} | prqlc debug lineage输出包含frames每个变换帧对应的 Span 与列集合、nodes表达式图节点含 id、kind、span、targets、children、parent 等属性和ast解析后的 PL 抽象语法树。该能力由prqlc::internal::pl_to_lineagelib.rs提供适合做数据血缘可视化或列影响分析。作为 Rust 库使用 prqlc除了 CLIprqlc最重要的定位是作为 Rust 库嵌入应用。库文档位于 lib.rs最常用的入口是prqlc::compile包装函数。添加依赖cargo add prqlc最小示例编译为 SQLite 方言// 在文件 src/main.rs 中 use prqlc::{compile, Options, DisplayOptions, Target, sql::Dialect}; let prql from employees | select {name, age}; let opts Options { format: false, target: Target::Sql(Some(Dialect::SQLite)), signature_comment: false, display: DisplayOptions::Plain, ..Default::default() }; let sql compile(prql, opts).unwrap(); assert_eq!(SELECT name, age FROM employees, sql);更简洁的链式写法见 lib.rs 的 doctestuse prqlc::{compile, Options, Target, sql::Dialect}; let prql from employees | select {name,age}; let opts Options::default() .with_target(Target::Sql(Some(Dialect::SQLite))) .with_signature_comment(false) .with_format(false); let sql compile(prql, opts).unwrap(); assert_eq!(SELECT name, age FROM employees, sql);Options配置结构Options定义在 lib.rs字段及默认值如下字段默认值说明formattrue是否把生成的 SQL 通过格式化器美化多行、缩进targetTarget::Sql(None)编译目标与方言signature_commenttrue是否在 SQL 末尾附加编译器版本签名注释colortrue已废弃由display取代displayDisplayOptions::AnsiColor错误信息是否使用 ANSI 颜色Plain或AnsiColor配套的 builder 方法包括with_format/no_format、with_signature_comment/no_signature、with_target、with_display。错误信息渲染支持在Plain模式下自动剥离 ANSI 转义序列见 lib.rs方便嵌入日志系统。更细粒度的 APIprqlc库还暴露了分阶段 API对应编译器流水线的各环节prql_to_tokensPRQL 字符串 → 词法表示LRprql_to_pl/prql_to_pl_treePRQL → PL ASTpl_to_rq/pl_to_rq_treePL → RQRelational QueryAST包含语义解析rq_to_sqlRQ → SQL 字符串pl_to_prqlPL AST 重新生成 PRQL供fmt使用json::from_pl/json::to_pl/json::from_rq/json::to_rqAST 与 JSON 互转。这些 API 在 lib.rs 中定义。SourceTree结构lib.rs则用于表示单文件或整个项目目录支持多文件项目的编译。在构建期编译 SQL宏与 build.rs官方推荐两种构建期编译方式见 lib.rs内联字符串使用宏——prqlc-macroscrate 提供prql_to_sql!let sql: str prql_to_sql!(from albums | select {title, artist_id});整文件编译调用build.rs——参考 examples/compile-files 示例在build.rs中遍历queries/目录调用prqlc::compile把每个.prql编译为.sql写入OUT_DIR再通过include_query!宏examples/compile-files/src/main.rs在编译期把 SQL 文本嵌入二进制。核心逻辑// build.rs 中 let sql_string compile(prql_string, Options::default()).unwrap(); fs::write(sql_path, sql_string).unwrap();编译流水线prqlc 是如何工作的想要深入理解prqlc的编译行为可以阅读仓库中的 ARCHITECTURE.md该文档也被include_str!嵌入了 lib.rs 的库文档。编译过程分三大阶段阶段子阶段使用的 ASTparselexerstring → LR词法表示parseparserLR → PR语法表示semanticast_expand / resolver / flatten / loweringPR → PL → RQ关系查询sqlpreprocess / pq-compiler / postprocess / sql-compiler / codegenRQ → PQ分区查询→sqlparser::ast→ string词法与语法解析PRQL 源码经 Chumsky 解析器切分为 token 流LR再解析为 PR 抽象语法树。语义分析解析名称引用、提取声明、为每个表达式确定血缘lineage即每一步的列集合构建RootModule名称空间随后把 PR 降级为更严格类型化的 RQ。SQL 后端把 RQ 转换为 PQ 中间 AST再生成 SQL。关键机制是锚定anchoring从后往前遍历管道在遇到不兼容的变换如 WHERE 中的窗口函数处把管道拆分为多个可独立表示成 SELECT 的原子管道由 sql/pq/context.rs 中的AnchorContext跟踪表实例、列定义与列名。prqlc compile的完整调用链在 cli/mod.rs 中可见prql_to_pl_tree→pl_to_rq_tree→rq_to_sql并把错误通过composed组装成带源码位置的高可读性报告。例如对非法输入asdf编译会给出带箭头标注位置的错误信息见 cli/mod.rs 中的测试Error: ╭─[ :1:1 ] │ 1 │ asdf │ ──┬─ │ ╰─── Unknown name asdf ───╯Feature 开关与二进制体积作为库使用时prqlc提供以下 feature flags见 Cargo.tomlFeature说明cli启用prqlcCLI 二进制默认开启作为库被其他 Rust crate 引用时可关闭lsp启用语言服务器协议支持默认关闭仅提供 stub 命令serde_yaml支持 AST 的 YAML 序列化/反序列化test-dbs启用进程内测试数据库SQLite、DuckDB显著增加编译时间test-dbs-external启用外部测试数据库Postgres、MySQL、MSSQL需要 Docker 容器另外默认构建的 Linux 二进制可能超过 20MB原因是解析器携带了大量 debuginfo 符号。可以按 lib.rs 的建议在自己的Cargo.toml中配置[profile.release.package.prqlc] strip debuginfo将体积贡献降到约 7MB。项目级编译多文件项目prqlc支持把整个目录视为一个项目编译目录下所有.prql文件会被聚合为一个SourceTree通过MAIN_PATH指定入口。仓库的 tests/integration/project 就是一个多文件示例Project.prql定义favorite_artists常量并执行join side:left artists.input (artist_id)artists.prql定义artists.input表从artists.parquet读取。对应的 CLI 用法见 cli/test.rs 的compile_project测试prqlc compile ./project - main编译结果会以 CTE 链的形式输出完整 SQL。这为一个项目一组 PRQL 文件的数据工程工作流提供了基础。结语prqlc既是一个零依赖的查询编译命令行工具也是一个可深度嵌入的 Rust 库。通过prqlc compile配合 DuckDB 等 SQL 执行器可以快速搭建PRQL 写查询 → SQL 执行的日常工作流通过-t参数与Options配置可以精确控制目标方言与输出格式而debug lineage、debug json-schema、--debug-log等工具则为理解编译器行为提供了透明通道。无论你是想替换手写 SQL、为数据平台内置 PRQL 支持还是想研究编译器实现prqlc/prqlc 都是一个值得深入阅读的参考实现。【免费下载链接】prqlPRQL is a modern language for transforming data — a simple, powerful, pipelined SQL replacement项目地址: https://gitcode.com/gh_mirrors/pr/prql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考