文档中心

AI 原生 BaaS 平台 Supabase 版

插件

混合事务分析处理（pg_duckdb）

pg_duckdb 插件在 PostgreSQL 数据库中集成了高性能的 DuckDB 分析引擎，使你能够直接在当前数据库环境内对关系型数据或对象存储（如 TOS）中的 Parquet、CSV 等格式文件进行高速分析查询，实现混合事务分析处理（HTAP）能力。

利用该插件，你可以加速即时分析：对于大规模表的复杂聚合查询，通过 DuckDB 的列式向量化引擎获得数十倍甚至上百倍的性能提升，而无需将数据 ETL 到专门的分析型数据库。

适用范围

2026 年 4 月 20 日以后创建的使用 PostgreSQL 引擎的 Workspace。

安装与启用

启用 pg_duckdb 插件分为两个核心步骤：创建开启了 AP 加速能力的 Workspace，以及由数据库所有者（DB Owner）在数据库中创建插件。

创建开启了 AP 加速能力的 Workspace 调用 CreateWorkspace 接口，创建开启了 AP 加速能力的 Workspace。

由 DB Owner 创建插件实例重启后，使用具有数据库 CREATE 权限的账号（通常是数据库的所有者）连接到目标数据库，并执行以下命令来创建插件：

执行成功后，pg_duckdb 插件在该数据库中即被启用。

权限说明

CREATE EXTENSION 操作需要数据库的 CREATE 权限，通常仅限于数据库所有者（DB Owner）或超级用户。普通用户无法执行此操作。

核心功能与操作

插件启用后，所有用户均可使用其提供的功能。核心操作包括强制使用 DuckDB 引擎进行查询、访问外部对象存储数据等。

使用 DuckDB 引擎加速查询

对于已存在于 PostgreSQL 中的表，你可以通过设置参数来强制查询通过 DuckDB 引擎执行，以获得分析性能的提升。

操作流程：

设置会话参数：在执行查询前，首先设置以下两个参数。

执行分析查询：正常编写你的 SQL 查询。例如，对 orders 表进行按日期的聚合统计。

验证执行计划：你可以使用 EXPLAIN 命令来验证查询是否确实由 DuckDB 引擎执行。

如果返回的执行计划中包含 Custom Scan (DuckDBScan) 和 DuckDB Execution Plan 字样，则说明查询已成功交由 DuckDB 处理。

何时使用 duckdb.force_execution？

当你的查询主要是复杂的聚合、多表连接等分析类（AP）操作时，建议开启此选项以获得最佳性能。

对于简单的点查或事务性（TP）操作，无需开启，使用 PostgreSQL 原生引擎即可。

该参数仅在当前会话中生效，关闭会话后即失效。

创建 DuckDB 列存表

你可以在 PostgreSQL 中创建由 DuckDB 引擎管理的临时表，这些表是列式存储的，非常适合进行临时的、高性能的数据分析。

注意

目前 USING duckdb 语法仅支持创建 TEMP（临时）表。

管理与查看

你可以通过以下命令查看所有 pg_duckdb 相关的配置参数

数据湖读取

pg_duckdb 支持直接读取外部文件。常用函数包括：

read_parquet

read_json

read_csv

这几个函数都可以把外部文件作为查询输入源，适合直接查询对象存储或数据湖中的文件数据。

基本用法

这三个函数的返回类型都是 SETOF duckdb.row。

path 参数支持：

单个路径

路径数组（TEXT[]）

glob 模式

既可以读取远端文件，也可以读取本地文件。但读取本地文件通常要求实例已开启对应权限。

最简单的查询方式是直接展开全部列：

如果需要引用具体列，需要先给函数结果起别名，再通过 r['column_name'] 的方式取列：

read_parquet

用于读取 Parquet 文件。

函数签名：

示例：

说明

可选参数与 DuckDB 原生 read_parquet 基本保持一致。

支持通过 glob 一次读取多个 Parquet 文件。

read_csv

用于读取 CSV 文件。

函数签名：

示例：

说明

可选参数与 DuckDB 原生 read_csv 基本保持一致。

当前 columns 参数暂不支持。

nullstr 需要以 TEXT[] 形式传入。

read_json

用于读取 JSON 文件。

函数签名：

示例：

说明

可选参数与 DuckDB 原生 read_json 基本保持一致。

当前 columns 参数暂不支持。

使用说明

如果需要引用具体列，必须为读取函数指定别名，并通过 r['col'] 的方式访问列。

path 支持传入多个文件路径，也支持使用通配符批量读取文件。

权限与合规

插件使用权限：pg_duckdb 插件安装后，数据库内的所有用户均有权限连接并使用 DuckDB 引擎执行查询，无需额外授权。

外部数据访问：当通过插件访问外部数据源（如 TOS、S3）时，数据安全由你提供的访问凭证（AK/SK）和底层云服务自身的 IAM 策略保障。插件本身不存储这些凭证，仅在当前会话中使用。请确保你使用的凭证遵循最小权限原则。

常见问题（FAQ）

Q1: 如何判断我的查询是否成功由 DuckDB 引擎执行了？A: 在你的查询语句前加上 EXPLAIN。如果返回的执行计划中包含 Custom Scan (DuckDBScan) 和 DuckDB Execution Plan 字样，就说明 DuckDB 引擎已经被使用。否则，查询仍由 PostgreSQL 原生引擎执行。

Q2: CREATE TABLE ... USING duckdb 为什么只能创建临时表？A: 这是当前版本的设计。DuckDB 表主要用于临时性的高性能分析，数据生命周期与当前数据库会话绑定。

最近更新时间：2026.07.28 16:31:13

这个页面对您有帮助吗？

有用

无用