AgensGraph并不是在PostgreSQL之上简单封装一套图查询接口，而是把图存储、图遍历引擎和关系型执行器放在同一个事务与存储体系内。它基于PostgreSQL内核扩展而来，保留完整的关系表、SQL、索引、触发器、存储过程等能力，同时增加属性图模型和Cypher查询语言。也就是说，开发者可以在同一个连接里先创建普通关系表，再创建图对象，然后一条SQL语句把表数据和图匹配结果关联起来，中途不需要切换数据源。
这种设计对已经深度使用PostgreSQL的团队尤其友好。原有的备份恢复、权限体系、连接池、监控工具大部分可以继续复用，不需要为了引入图能力而单独维护一套图数据库集群。同时，AgensGraph对图查询的优化也不只是简单翻译成SQL递归，它在执行层实现图遍历算子，并支持图专用索引，避免深层次关系查询退化成低效的逐级JOIN。
一、AgensGraph的多模存储架构是怎么设计的
理解AgensGraph的关键，是搞清楚它如何把图数据映射到关系存储，同时不破坏PostgreSQL原有的事务模型。AgensGraph在PostgreSQL的目录系统里增加了图、顶点表、边表等对象类型。当用户使用CREATE GRAPH创建图时，底层会生成对应的关系表结构，顶点和边分别存储在不同的物理表中，并继承PostgreSQL的MVCC、WAL日志、锁机制等能力。
属性图模型里，顶点可以带标签和属性，边可以有方向、类型和属性。AgensGraph把这些信息拆解为内部列，例如系统内部会为每个顶点分配图空间ID、顶点ID、起始边位置等隐藏列。这样做的目的是让遍历操作可以直接通过索引定位邻居节点，而不需要扫描整张表。对于边表，AgensGraph会同时维护出边和入边的访问路径，保证从一个顶点向任意方向扩展时都能快速找到相邻边。
下面这段SQL展示了如何创建一个图，并向图中添加顶点和边。可以看出语法与PostgreSQL非常接近，但增加了图对象的定义能力。
CREATE GRAPH social_graph;
ALTER GRAPH social_graph ADD VERTEX person;
ALTER GRAPH social_graph ADD VERTEX company;
ALTER GRAPH social_graph ADD EDGE works_at;
INSERT INTO social_graph.person VALUES ('p1', 'Alice', 30);
INSERT INTO social_graph.person VALUES ('p2', 'Bob', 34);
INSERT INTO social_graph.company VALUES ('c1', 'Acme', 'Seoul');
INSERT INTO social_graph.works_at
SELECT v1.id, v2.id, jsonb_build_object('since', 2021)
FROM social_graph.person v1, social_graph.company v2
WHERE v1.id = 'p1' AND v2.id = 'c1';
从这里可以看到，图对象存在于独立的schema命名空间下，顶点和边都可以像表一样通过SQL插入。这种存储方式让熟悉PostgreSQL的开发者可以快速上手，也意味着关系表和图对象之间可以做跨模式查询。不过，直接用SQL插入图数据虽然直观，却无法发挥图查询在路径表达上的优势，这时就需要Cypher参与。
二、在AgensGraph中如何同时使用SQL与Cypher
AgensGraph最突出的能力是支持SQL和Cypher的混合使用。Cypher是一种声明式图查询语言，用MATCH描述路径模式，例如(a:person)-[:knows]->(b:person)表示查找所有认识关系。AgensGraph会把Cypher语句编译成内部的图执行计划，而不是把它当作某种外挂解析器。这个编译过程与SQL优化器协同工作，使得一条查询可以同时包含关系扫描和图遍历。
要在一个查询块里混合两种语言，AgensGraph提供了一个特殊的函数式调用写法。开发者可以在SQL的FROM子句里使用cypher()函数，把Cypher查询作为子查询结果返回。反过来，Cypher内部也可以引用已经创建的普通关系表。这样，应用层不需要先查一遍图、再查一遍关系库、再在内存里做合并，数据库自己就能完成跨模型关联。
SELECT p.props->>'name' AS person_name,
c.props->>'name' AS company_name,
e.props->>'since' AS since_year
FROM cypher('social_graph', $$
MATCH (p:person)-[e:works_at]->(c:company)
RETURN p, e, c
$$) AS (p agtype, e agtype, c agtype);
这段SQL把Cypher模式匹配的结果作为虚拟表使用，外层继续用PostgreSQL的JSON函数处理属性。注意返回类型agtype是AgensGraph定义的JSONB变体，它保留了图数据的类型信息。这种混合方式非常适合在现有业务系统中逐步引入图能力，团队可以先保留原有关系查询，再在关键路径上补充Cypher遍历。
反之，如果想在Cypher查询中使用关系表，也可以先把关系表转换成图对象，或者通过图视图进行映射。AgensGraph支持从现有表创建图，这一能力让已有PostgreSQL数据库能够以较低成本获得图查询入口。需要注意的是，混合查询虽然方便，但对执行计划的稳定性要求更高，尤其是当Cypher返回结果集很大时，外层SQL的过滤条件可能无法下推到图遍历内部，需要根据执行计划做调整。
三、多模能力下的典型场景与避坑建议
多模数据库并不是万能的，AgensGraph在适合的场景里能明显减少架构复杂度。例如权限系统的继承关系、社交网络的好友推荐、供应链中的依赖链路、金融领域的资金流向分析。这些场景的共同点是既有大量结构化属性需要过滤，又依赖多跳关系计算。传统做法往往是把结构数据放在关系库，把关系数据放在图库，然后通过消息或应用层同步，带来一致性和延迟问题。AgensGraph可以在同一个库里完成两者，事务边界也更清晰。
但在图遍历深度较大的时候，需要特别关注资源消耗。Cypher的MATCH语句如果写成可变长度路径，例如(a)-[:knows*1..6]->(b)，在数据量较大且边分布很宽时，遍历节点数量会呈指数级增长。此时建议在中间顶点上添加过滤条件，或者使用图专用索引限制扩展方向。AgensGraph虽然基于PostgreSQL，但图遍历的内存占用和执行时间特性与普通SQL不同，必须单独压测。
SELECT * FROM cypher('social_graph', $$
MATCH (a:person {id: 'p1'})-[:knows*1..4]->(b:person)
WHERE b.props->>'active' = 'true'
RETURN DISTINCT b
$$) AS (b agtype);
这段查询限定了起始顶点和最大深度，但在生产环境中仍然可能出现大范围扇出。一个更稳妥的做法是降低最大深度，或者把边属性纳入模式，例如只遍历最近两年的转账关系。如果业务确实需要很深的路径分析，可以考虑使用AgensGraph的图分析函数或分批游标，避免一次性把全部结果加载到内存。
另一个容易踩坑的地方是索引。PostgreSQL默认的B-tree索引对图遍历的邻居定位并不总是最优，AgensGraph提供了图索引类型，可以加速特定标签和边类型的访问。创建图后，如果查询模式固定，应主动为热路径建立索引，否则图遍历会退化为顺序扫描。尤其是在混合SQL与Cypher时，外层条件能否命中索引直接决定整个查询的延迟。
四、部署与优化中的关键配置
AgensGraph作为PostgreSQL的扩展，部署时首先需要选择兼容的PostgreSQL主版本。它通常以源码或二进制包形式安装，安装后会创建自己的扩展控制文件。启动数据库后，需要在会话或配置中启用图相关参数。对于生产环境，建议把图缓冲区和普通共享缓冲区分开监控，因为图遍历会产生大量随机访问，缓存命中率对性能影响很大。
在参数优化方面，除了常规的shared_buffers、work_mem之外，还要关注图执行器的内存上限。AgensGraph在执行大规模遍历时会申请临时内存，如果限制过小，查询会频繁落盘；如果设置过大，则可能挤占PostgreSQL本身的内存空间。通常的做法是根据单次遍历的深度和平均出度数估算中间结果集大小，再结合压测确定合适阈值。
-- 查看与AgensGraph相关的运行参数 SHOW agens.graph_path; SHOW work_mem; SHOW shared_buffers;
备份恢复方面，AgensGraph的图数据和普通表一样被包含在PostgreSQL的物理备份与逻辑导出中。使用pg_dump时，图对象会以扩展DDL的形式导出，恢复时需要先创建扩展再导入数据。因此，最好在恢复流程里明确扩展创建顺序。对于跨版本升级，建议先在测试环境验证图对象的兼容性，因为图目录结构与PostgreSQL版本强相关。
从架构角度看，AgensGraph适合那些已经把PostgreSQL作为主存储，并且图关系与关系属性紧密耦合的系统。如果图数据量达到数百亿边，或者需要分布式图计算，单节点AgensGraph可能不够，需要评估其分布式方案或与专用图计算框架配合。但在大多数中等规模业务里，把关系表和图遍历放进同一个事务、同一套权限、同一份备份里，带来的收益非常明显。
AgensGraph多模数据库图数据库修改时间：2026-08-13 02:55:15