graph

PostgreSQL 图查询与遍历扩展

概览

扩展包名版本分类许可证语言
pggraph0.1.7FEATApache-2.0Rust
ID扩展名BinLibLoadCreateTrustReloc模式
2630graph-
相关扩展age agtype pg_graphql

PGXN distribution and package are pggraph; installed extension name is graph.

版本

类型仓库版本PG 大版本包名依赖
EXTPIGSTY0.1.71817161514pggraph-
RPMPIGSTY0.1.71817161514pggraph_$v-
DEBPIGSTY0.1.71817161514postgresql-$v-pggraph-
OS / PGPG18PG17PG16PG15PG14
el8.x86_64
el8.aarch64
el9.x86_64
el9.aarch64
el10.x86_64
el10.aarch64
d12.x86_64
d12.aarch64
d13.x86_64
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
d13.aarch64
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
u22.x86_64
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
u22.aarch64
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
u24.x86_64
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
u24.aarch64
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
PIGSTY 0.1.7
u26.x86_64
u26.aarch64

构建

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

pig build pkg pggraph         # 构建 RPM / DEB 包

安装

您可以直接安装 pggraph 扩展包的预置二进制包,首先确保 PGDGPIGSTY 仓库已经添加并启用:

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

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

pig install pggraph;          # 当前活跃 PG 版本安装
pig ext install -y pggraph -v 18  # PG 18
pig ext install -y pggraph -v 17  # PG 17
pig ext install -y pggraph -v 16  # PG 16
pig ext install -y pggraph -v 15  # PG 15
pig ext install -y pggraph -v 14  # PG 14
dnf install -y pggraph_18       # PG 18
dnf install -y pggraph_17       # PG 17
dnf install -y pggraph_16       # PG 16
dnf install -y pggraph_15       # PG 15
dnf install -y pggraph_14       # PG 14
apt install -y postgresql-18-pggraph   # PG 18
apt install -y postgresql-17-pggraph   # PG 17
apt install -y postgresql-16-pggraph   # PG 16
apt install -y postgresql-15-pggraph   # PG 15
apt install -y postgresql-14-pggraph   # PG 14

创建扩展

CREATE EXTENSION graph;

来源:pgGraph v0.1.7 READMEQuickstartSQL API ReferenceSchema RegistrationConfiguration

用法

pggraph 是包名与 PGXN 发行名,但安装到 PostgreSQL 中的扩展名是 graph。该扩展会从普通 PostgreSQL 表构建派生图索引,并以这些表作为事实来源,通过 graph schema 提供图搜索、遍历、GQL 风格模式读取和路径函数。

上游项目将 v0.1.7 标记为早期 alpha。建议先在可丢弃或开发数据库中使用,并从源表重建图,而不是把生成的图产物当作权威数据。

基本图构建

CREATE EXTENSION IF NOT EXISTS graph;
SELECT graph.reset();

CREATE TABLE companies (
  id   text PRIMARY KEY,
  name text NOT NULL
);

CREATE TABLE people (
  id         text PRIMARY KEY,
  name       text NOT NULL,
  company_id text REFERENCES companies(id)
);

INSERT INTO companies VALUES
  ('c1', 'Acme Bank'),
  ('c2', 'Northwind Trading');

INSERT INTO people VALUES
  ('p1', 'Alice', 'c1'),
  ('p2', 'Bob', 'c1'),
  ('p3', 'Carol', 'c2');

SELECT * FROM graph.auto_discover('public');

SELECT node_count, edge_count, edge_types
FROM graph.status();

graph.auto_discover('public') 会扫描该 schema 中的主键和外键,注册发现到的源表与边,然后构建图。对于生产 schema,建议使用显式注册,确保标签、搜索列、权重和租户行为都经过有意设计。

手工注册

SELECT graph.reset();

SELECT graph.add_table(
  table_name := 'public.people'::regclass,
  id_column  := 'id',
  columns    := ARRAY['name']
);

SELECT graph.add_table(
  table_name := 'public.companies'::regclass,
  id_column  := 'id',
  columns    := ARRAY['name']
);

SELECT graph.add_edge(
  from_table    := 'public.people'::regclass,
  from_column   := 'company_id',
  to_table      := 'public.companies'::regclass,
  to_column     := 'id',
  label         := 'works_at',
  bidirectional := true
);

SELECT * FROM graph.build();

节点标识符必须匹配主键,或匹配唯一的 NOT NULL 索引。columns 控制可用于搜索和 GQL 的源表属性。遍历过滤下推需要通过单独的 graph.add_filter_column() 注册。

搜索、遍历与路径

SELECT node_table_name, node_id, node
FROM graph.search(
  property_key  := 'name',
  property_value := 'Alice',
  table_filter  := 'public.people'::regclass,
  mode          := 'exact',
  hydrate       := true
);

SELECT depth, node_table_name, node_id, edge_path
FROM graph.traverse(
  'public.people'::regclass,
  'p1',
  2,
  hydrate := false
);

SELECT step, node_table_name, node_id, edge_label
FROM graph.shortest_path(
  'public.people'::regclass,
  'p1',
  'public.companies'::regclass,
  'c1',
  hydrate := false
);

hydrate := false 返回紧凑的图坐标。启用 hydration 后,源行可见性仍由 PostgreSQL ACL 和 RLS 控制,过期坐标会失败关闭,而不会伪造行。

GQL 查询

SELECT row
FROM graph.gql(
  'MATCH (p:people)-[:works_at]->(c:companies)
   WHERE p.name = $name
   RETURN p.id AS person_id, c.name AS company
   ORDER BY company',
  params  := '{"name":"Alice"}'::jsonb,
  hydrate := true
);

graph.gql() 为每条 SQL 行返回一个 jsonb 对象。节点标签映射到已注册的表名,关系类型映射到已注册的边标签。支持的 GQL/openCypher 子集覆盖常见读取、有界路径、部分聚合,以及在启用 mutable overlay 时的窄范围映射写入。

运维注意事项

  • 注册信息变更后,或源表发生所选同步模式未覆盖的变化后,需要用 graph.build() 重建。
  • 动态边标签使用紧凑 ID;v0.1.7 最多支持 254 个面向用户的边标签。
  • 加权最短路径需要数值型 weight_column;缺失或 NULL 的权重默认为 1
  • 重要 GUC 包括 graph.max_nodesgraph.max_frontiergraph.memory_limit_mbgraph.query_freshnessgraph.default_projection_modegraph.mutable_enabled
  • 映射式 GQL 写入需要 graph.default_projection_mode = 'mutable_overlay'graph.mutable_enabled = on

最后修改 2026-06-18: extension data update (63e2bd9)