pg_lake_engine

概览

Query-engine component. pg_extension_base auto-loads its module; delegated DuckDB execution additionally requires the separately running PG-major pgduck_server. Extension SQL/control version is 3.4; source and DEB/RPM package version is 3.4.0.

版本

构建

您可以使用 pig build 命令构建 pg_lake 扩展的 RPM / DEB 包：

pig build pkg pg_lake         # 构建 RPM / DEB 包

安装

您可以直接安装 pg_lake 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

• 安装
• pig
• dnf
• apt

pig install pg_lake;          # 当前活跃 PG 版本安装

pig ext install -y pg_lake -v 18  # PG 18
pig ext install -y pg_lake -v 17  # PG 17
pig ext install -y pg_lake -v 16  # PG 16

dnf install -y pg_lake_18       # PG 18
dnf install -y pg_lake_17       # PG 17
dnf install -y pg_lake_16       # PG 16

apt install -y postgresql-18-pg-lake   # PG 18
apt install -y postgresql-17-pg-lake   # PG 17
apt install -y postgresql-16-pg-lake   # PG 16

预加载配置：

shared_preload_libraries = 'pg_extension_base';

创建扩展：

CREATE EXTENSION pg_lake_engine CASCADE;  -- 依赖: pg_extension_base, pg_map

用法

来源：

• 官方pg_lake架构概述
• 版本3.4控制文件
• 基础SQL对象
• 版本3.4清理队列变更

pg_lake_engine是pg_lake表、复制和Iceberg扩展共享的执行层。它重写符合条件的PostgreSQL工作以供pgduck_server使用，映射PostgreSQL和DuckDB值，并跟踪在中止或表变更后必须删除的远程文件。它是内部依赖项而非独立的分析接口。

部署边界

通过顶级扩展安装它，使其依赖图和预加载指令保持一致：

shared_preload_libraries = 'pg_extension_base'

CREATE EXTENSION pg_lake CASCADE;

pg_lake_engine需要pg_extension_base和pg_map。查询执行还需要一个运行中的本地pgduck_server；仅创建此扩展不会提供可用的湖表。

用户可见对象

• 角色lake_read、lake_write和lake_read_write：被其他组件消费的共享权限组。
• to_postgres(any)：返回其输入并强制该表达式在PostgreSQL中而不是推送到湖引擎中进行评估。
• to_date(double precision)：将常见的Parquet中的天数自Unix纪元值转换为PostgreSQL date。
• lake_engine.deletion_queue：跟踪已提交的孤儿文件清理；可由lake_write读取。
• lake_engine.in_progress_files：跟踪未提交事务产生的文件。
• lake_engine.flush_deletion_queue(regclass)和flush_in_progress_queue()：用于维护路径的特权清理函数。

SELECT to_postgres(application_only_function(payload))
FROM external_events;

仅在表达式无法或不应下推时使用to_postgres()；将数据拉回PostgreSQL可能会显著增加传输和执行成本。

内部状态与注意事项

• __lake__internal__nsp__函数是规划器/解析器占位符，不是受支持的直接SQL API。
• 不要手动更新或删除队列行。清理函数需要扩展的对象存储凭证和特权角色，并且仅应在操作工具文档中指定的情况下调用。
• 版本3.4将resolve_metadata添加到删除队列，以便在VACUUM期间可以将Iceberg元数据展开为精确引用的文件，从而将对象存储遍历移出DROP路径。
• 角色是集群范围的对象，在一个数据库中可能会超出扩展实例的存在；在移除pg_lake时需单独审查成员资格。