pgbson

概览

Release tag 2.0.2 still ships extension SQL version 2.0; PGXN dist name is bson, CREATE EXTENSION name is pgbson, RPM package root is postgresbson, and the runtime dependency is libbson.

版本

构建

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

pig build pkg pgbson         # 构建 RPM / DEB 包

安装

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

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

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

• 安装
• pig
• dnf
• apt

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

pig ext install -y pgbson -v 18  # PG 18
pig ext install -y pgbson -v 17  # PG 17
pig ext install -y pgbson -v 16  # PG 16
pig ext install -y pgbson -v 15  # PG 15
pig ext install -y pgbson -v 14  # PG 14

dnf install -y postgresbson_18       # PG 18
dnf install -y postgresbson_17       # PG 17
dnf install -y postgresbson_16       # PG 16
dnf install -y postgresbson_15       # PG 15
dnf install -y postgresbson_14       # PG 14

apt install -y postgresql-18-pgbson   # PG 18
apt install -y postgresql-17-pgbson   # PG 17
apt install -y postgresql-16-pgbson   # PG 16
apt install -y postgresql-15-pgbson   # PG 15
apt install -y postgresql-14-pgbson   # PG 14

创建扩展：

CREATE EXTENSION pgbson;

用法

来源：README, META.json 2.0.2, pgbson.control

pgbson 增加了 BSON 数据类型，以及感知 BSON 的访问器与操作符。上游文档将包版本标为 2.0.2，而扩展 control 文件暴露的 SQL 默认版本仍是 2.0；这与其打包说明一致，即发行包版本领先于扩展 SQL 版本。

CREATE EXTENSION pgbson;

核心访问模式

类型化 dotpath 访问器

类型化 dotpath 访问器会直接遍历 BSON 结构，是上游推荐的快速路径：

SELECT bson_get_datetime(bson_column, 'msg.header.event.ts') FROM my_table;
SELECT bson_get_bson(bson_column, 'msg.header.event') FROM my_table;
SELECT bson_get_string(bson_column, 'data.payload.product.definition.id') FROM my_table;

JSON 风格操作符

也支持 JSON 风格的操作符：

SELECT (bson_column->'msg'->'header'->'event'->>'ts')::timestamp
FROM my_table;

主要函数与操作符

• 类型化 getter，例如 bson_get_string、bson_get_int32、bson_get_int64、bson_get_double、bson_get_decimal、bson_get_datetime、bson_get_binary 与 bson_get_boolean。
• bson_get_bson 用于返回 BSON 子文档。
• bson_get_jsonb_array 适合在路径解析到数组后继续使用原生 jsonb 数组操作符。
• 箭头操作符 -> 与 ->>，用法接近 PostgreSQL JSON 类型。
• 通过 Extended JSON 转成 json/jsonb，以保留类型精度。

互操作与索引

需要 PostgreSQL JSON 操作符时，可先将 BSON 转成 jsonb：

SELECT (bson_get_bson(bson_column, 'msg.header.event')::jsonb) ?& ARRAY['id', 'type']
FROM my_table;

也可以在提取路径上建立表达式索引：

CREATE INDEX ON data_collection (bson_get_string(data, 'd.recordId'));

README 还说明 BSON 值可通过 bytea cast 实现字节级 round-trip。

注意事项

• dotpath 访问器通常比长链式 -> 访问更快、更省内存，因为它不会物化中间子结构。
• bson_get_bson() 在路径终点是 scalar 时会返回 NULL，因为简单标量不是 BSON 文档。
• 上游明确指出，数组处理与错误类型访问器行为的人机工学仍有待改进。