云数据库 PostgreSQL Apache AGE 图数据库使用指南

一、概述

核心特点：

·在 PostgreSQL 内原生支持属性图模型。

·使用 openCypher 语法（兼容 Neo4j 查询语法）。

·可与 SQL 混合查询，实现图 + 关系数据联合分析。

·支持 ACID 事务。

二、前提条件

云数据库 PostgreSQL 实例版本 ≥ 13。

三、安装与启用

— 创建 Apache AGE 扩展CREATE EXTENSION IF NOT EXISTS age;– 将 ag_catalog 加入 search_pathSET search_path = ag_catalog, "$user", public;– 或永久设置（推荐）ALTER DATABASE mydb SET search_path = ag_catalog, "$user", public;

四、核心概念

五、创建图

— 创建一个新图SELECT create_graph('knowledge_graph');

六、创建节点

— 创建带标签和属性的节点SELECT * FROM cypher('knowledge_graph', $$ CREATE (n:Person {name: '张三', age: 30, role: 'Engineer'}) RETURN n$$) AS (node agtype);– 批量创建节点SELECT * FROM cypher('knowledge_graph', $$ CREATE (a:Person {name: '李四', role: 'Manager'}), (b:Company {name: '腾讯云', industry: 'Cloud'}), (c:Technology {name: 'PostgreSQL', type: 'Database'}) RETURN a, b, c$$) AS (a agtype, b agtype, c agtype);

七、创建关系（边）

— 创建节点之间的关系SELECT * FROM cypher('knowledge_graph', $$ MATCH (p:Person {name: '张三'}), (c:Company {name: '腾讯云'}) CREATE (p)-[r:WORKS_AT {since: '2020-01-01'}]->(c) RETURN r$$) AS (rel agtype);– 创建使用关系SELECT * FROM cypher('knowledge_graph', $$ MATCH (p:Person {name: '张三'}), (t:Technology {name: 'PostgreSQL'}) CREATE (p)-[r:USES {level: 'expert'}]->(t) RETURN r$$) AS (rel agtype);

八、查询

— 查找所有 Person 节点SELECT * FROM cypher('knowledge_graph', $$ MATCH (n:Person) RETURN n.name, n.role$$) AS (name agtype, role agtype);– 查找关系路径SELECT * FROM cypher('knowledge_graph', $$ MATCH (p:Person)-[r:WORKS_AT]->(c:Company) RETURN p.name, c.name, r.since$$) AS (person agtype, company agtype, since agtype);– 多跳查询SELECT * FROM cypher('knowledge_graph', $$ MATCH (p:Person)-[:WORKS_AT]->(c:Company), (p)-[:USES]->(t:Technology) RETURN p.name, c.name, t.name$$) AS (person agtype, company agtype, tech agtype);– 路径查询（2-3 跳）SELECT * FROM cypher('knowledge_graph', $$ MATCH path = (a:Person)-[*2..3]->(b) RETURN path$$) AS (path agtype);

九、更新与删除

— 更新节点属性SELECT * FROM cypher('knowledge_graph', $$ MATCH (p:Person {name: '张三'}) SET p.age = 31 RETURN p$$) AS (node agtype);– 删除关系SELECT * FROM cypher('knowledge_graph', $$ MATCH (p:Person {name: '张三'})-[r:USES]->(t:Technology) DELETE r$$) AS (result agtype);– 删除节点（需先删除关联的边）SELECT * FROM cypher('knowledge_graph', $$ MATCH (t:Technology {name: 'PostgreSQL'}) DETACH DELETE t$$) AS (result agtype);

十、SQL 与 Cypher 混合查询

Apache AGE 的强大之处在于可以将图查询结果与关系表 JOIN：

— 图查询结果与关系表联合SELECT g.person_name, u.email, u.departmentFROM ( SELECT * FROM cypher('knowledge_graph', $$ MATCH (p:Person)-[:WORKS_AT]->(c:Company {name: '腾讯云'}) RETURN p.name AS person_name $$) AS (person_name agtype)) gJOIN users u ON u.name = g.person_name::text;

十一、知识图谱

— 构建产品知识图谱SELECT create_graph('product_kg');SELECT * FROM cypher('product_kg', $$ CREATE (pg:Product {name: 'PostgreSQL', category: 'Database'}), (vec:Feature {name: '向量检索', desc: '基于 pgvector'}), (ai:Feature {name: 'AI 调用', desc: '基于 tencentdb_ai'}), (pg)-[:HAS_FEATURE]->(vec), (pg)-[:HAS_FEATURE]->(ai) RETURN pg, vec, ai$$) AS (pg agtype, vec agtype, ai agtype);

十二、GraphRAG（图增强的 RAG）

— 实体提取后存入图，检索时图 + 向量混合召回：– 1. 向量召回相关文档– 2. 从图中找到相关实体的关系链– 3. 将图上下文 + 文档内容一起送给大模型

十三、Agent 记忆关系图

— 记录 Agent 之间的交互关系SELECT * FROM cypher('agent_memory', $$ CREATE (a1:Agent {name: 'Planner', role: 'planning'}), (a2:Agent {name: 'Researcher', role: 'research'}), (a1)-[:DELEGATES {task: '调研竞品', timestamp: '2026-01-15'}]->(a2) RETURN a1, a2$$) AS (a1 agtype, a2 agtype);

十四、性能建议

1. 为频繁查询的属性创建索引：

— 在节点标签的属性上创建索引CREATE INDEX ON knowledge_graph."Person" ((properties->>'name'));

2. 合理设置路径查询的跳数上限，避免全图遍历。

3. 大规模图建议分区存储。

十五、注意事项

·需要将 ag_catalog 添加到 search_path。

·Cypher 查询通过 cypher() 函数调用，结果需要指定列类型。

·所有 Cypher 返回值类型为 agtype（Apache AGE 自定义的 JSON-like 类型）。

十六、相关文档

·pgvector 向量扩展使用指南。

·基于 Apache AGE 构建 GraphRAG 知识图谱应用。

·Apache AGE 产品文档。

·openCypher 规范。