pg_lake_table

概览

Loaded via pg_extension_base.

版本

构建

您可以使用 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 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_table CASCADE;  -- 依赖: btree_gist, pg_lake_engine, pg_lake_iceberg

用法

来源：

• 官方数据湖文件查询指南

• 官方Iceberg表指南

• 版本3.6控制文件

• 3.4 至 3.5 目录索引升级

• FDW、服务器、实用工具和访问方法SQL

• Upstream 3.6.0

• 3.5 to 3.6 SQL

pg_lake_table 将对象存储文件作为 PostgreSQL 外部表暴露，并提供 USING iceberg 表语法。它拥有 pg_lake 和 pg_lake_iceberg 外部服务器、文件检查/缓存实用工具、表目录和事务挂钩；Iceberg 元数据编码委托给 pg_lake_iceberg。

本次核验的上游发布为 3.6.0，SQL 扩展版本为 3.6，支持 PostgreSQL 16–19。现有软件包版本单独跟踪，动态库与查询服务器应使用同一发布版本。

查询外部文件

安装完整的堆栈，包括所需的 pg_lake_engine、pg_lake_iceberg 和 btree_gist 依赖项：

CREATE EXTENSION pg_lake CASCADE;

空列列表要求 pg_lake 推断文件模式：

CREATE FOREIGN TABLE external_events ()
SERVER pg_lake
OPTIONS (
    path 's3://analytics-bucket/events/*.parquet',
    filename 'true'
);

SELECT count(*) FROM external_events;

通过扩展提供的表访问方法创建可写的 Iceberg 表：

CREATE TABLE managed_events (
    event_time timestamptz,
    payload jsonb
) USING iceberg;

文件和表实用工具索引

• lake_file.list(pattern): 列出匹配的对象路径、大小、修改时间和 ETags。
• lake_file.size(path) 和 lake_file.exists(path): 检查一个远程对象。
• lake_file.preview(url, format, compression): 返回推断的列名和类型。
• lake_file.delete(url): 删除一个远程对象；仅限允许删除数据的角色执行。
• lake_file_cache.add(path, refresh), remove(path) 和 list(): 管理 lake_read 成员的本地文件缓存。
• lake_iceberg.table_size(regclass): 计算 Iceberg 表当前数据文件的总大小。
• 外部服务器 pg_lake 和 pg_lake_iceberg: 读取文件和可写的 Iceberg 入口点。
• 访问方法 iceberg 和 pg_lake_iceberg: 用于将 CREATE TABLE ... USING 转换为扩展的外部表表示形式的别名。

SELECT path, file_size
FROM lake_file.list('s3://analytics-bucket/events/**/*.parquet');

SELECT *
FROM lake_file.preview('s3://analytics-bucket/events/sample.parquet');

运维注意事项

• 必须预加载 pg_extension_base，并在每个执行湖查询的 PostgreSQL 主机上运行 pgduck_server，为其配置所需位置的访问凭据。
• lake_read、lake_write 和 lake_read_write 控制对外部服务器、模式和实用工具的访问。为每个应用程序授予最窄的角色权限。
• 外部表是文件的引用，而不是导入的副本。文件替换、跨区域访问和缓存失效可以独立于 PostgreSQL 目录状态改变延迟或结果。
• Iceberg 插入适合批量处理。对于高频率逐行插入，使用暂存堆表，并定期刷新批次。
• 内部 lake_table.* 目录跟踪文件、字段 ID、分区和恢复状态。不要直接修改它们。

版本 3.5 为文件删除映射、列统计与分区值目录新增索引，避免批量删除时反复扫描子目录。除安装新动态库外，还须执行 SQL 迁移。

上游 3.6.0

上游 3.6.0 增加 PostgreSQL 19 支持，并使用 DuckDB 1.5.6。应部署匹配动态库与 pgduck_server，保持预加载 pg_extension_base，重启加载旧库的进程，并执行所提供的 SQL 升级到 3.6。表组件注册独立的对象存储目录导出 worker，并将目录名称辅助函数改为 STABLE。必须执行 SQL 迁移，仅替换二进制不会注册该 worker。