图服务

更新时间:
复制 MD 格式

图服务是AnalyticDB for MySQL内嵌的属性图(Property Graph)能力。本文介绍如何开通图服务、建立数据模型、读写数据和常用查询。

前提条件

开通与使用

图服务适合大模型和Agent场景:将业务实体、知识、任务、工具或事件建模为图,为大模型提供可追溯的关联上下文、单跳/多跳关系查询和路径探索能力。它可与AnalyticDB for MySQL的结构化数据、分析计算以及行存引擎中的业务明细数据配合使用:图服务负责关系和遍历,其他AnalyticDB for MySQL能力负责明细存储、筛选、分析和统计。

使用图服务前,请提交工单申请开通。开通后,在AnalyticDB for MySQL的 SQL 执行页面直接运行 Gremlin 语句即可:

  • 使用graph.schema()定义数据模型和索引。

  • 使用g写入、查询、更新和删除数据。

  • 直接在页面查看执行结果或错误信息。

用户无需单独部署图数据库,也无需处理图服务的认证、集群识别或请求转发。

AI/Agent典型用法

  • 知识关联:查询实体、产品、文档、规则之间的关系,补足大模型回答的上下文。

  • Agent路径与依赖:查询任务、工具、数据集、责任人之间的依赖和影响范围。

  • 风险与溯源:从一个客户、设备或事件出发,找到相关关系和传播路径。

  • 联合分析:先通过图遍历缩小关联对象范围,再结合AnalyticDB for MySQL和行存引擎的明细数据做条件过滤、分析或统计。

基础概念

图由三类对象组成:

对象

含义

示例

Vertex

顶点,表示业务实体

用户、设备、商品

Edge

边,表示实体间有方向的关系

关注、购买、调用

Property

顶点或边上的属性

名称、年龄、时间、权重

一个常见模型是:person顶点通过knows边关联另一个person顶点;顶点保存name、age,边保存since等关系属性。在AI/Agent场景中,可以将person替换为客户、文档、知识点、工具或任务,将knows替换为依赖、引用、归属、调用或影响等业务关系。

第一次建模

业务数据写入前必须先创建Schema。以下示例创建一个人员和认识关系模型:

graph.schema().propertyKey("name").asText().ifNotExist().create()
graph.schema().propertyKey("age").asInt().ifNotExist().create()
graph.schema().propertyKey("since").asLong().ifNotExist().create()

graph.schema().vertexLabel("person")
     .properties("name", "age")
     .nullableKeys("age")
     .useAutomaticId()
     .ifNotExist().create()

graph.schema().edgeLabel("knows")
     .sourceLabel("person")
     .targetLabel("person")
     .properties("since")
     .ifNotExist().create()

如需按名称或年龄查询,再创建索引:

graph.schema().indexLabel("personByName")
     .onV("person").by("name").secondary()
     .ifNotExist().create()

graph.schema().indexLabel("personByAge")
     .onV("person").by("age").range()
     .ifNotExist().create()

使用建议:

  • 高频等值查询使用secondary索引。

  • 数值或时间范围查询使用range索引。

  • 只为真实查询创建索引;索引越多,写入成本越高。

  • Schema的数据类型和Label结构不能直接修改,需要新建并迁移数据。

写入数据

创建顶点后,保存返回的顶点ID,后续查询和写边优先使用该ID:

# 返回 alice 的顶点 id aliceVertexId
g.addV("person").property("name", "alice").property("age", 25).next()

# 返回 bob 的顶点 id bobVertexId
g.addV("person").property("name", "bob").property("age", 30).next()

# 返回 caz 的顶点 id cazVertexId
g.addV("person").property("name", "caz").property("age", 30).next()

# 创建关系:alice -> bob -> caz
g.addE("knows").from(__.V(aliceVertexId)).to(__.V(bobVertexId)).property("since", 2024).iterate()
g.addE("knows").from(__.V(bobVertexId)).to(__.V(cazVertexId)).property("since", 2024).iterate()

大批量导入应分批执行,并从较小批次开始压测。重要业务建议使用稳定的业务ID或记录返回ID,以便在超时后核对实际写入结果。

常用查询

按ID点查:

g.V(vertexId).valueMap(true).next()
g.V(vertexId1, vertexId2).valueMap(true).toList()

按已建索引的属性查询:

g.V().hasLabel("person").has("name", "alice").limit(20).valueMap(true).toList()
g.V().hasLabel("person").has("age", gt(25)).limit(100).valueMap(true).toList()

从已知顶点进行单跳和两跳查询:

g.V(vertexId).out("knows").limit(20).valueMap(true).toList()
g.V(vertexId).out("knows").out("knows").dedup().limit(50).valueMap(true).toList()

在线查询建议从ID、索引条件或已知顶点开始,并始终设置limit。避免将全图count()、深分页和全局order().by(...).limit(...)放在高频在线请求中。

查询schema定义:

# 查询单个schema定义
graph.schema().getPropertyKey("name")
graph.schema().getVertexLabel("person")
graph.schema().getEdgeLabel("knows")
graph.schema().getIndexLabel("personByAge")

# 查询全局schema定义
graph.schema().getPropertyKeys().toList()
graph.schema().getVertexLabels().toList()
graph.schema().getEdgeLabels().toList()
graph.schema().getIndexLabels().toList()

删除

Schema删除属于耗时操作,页面会显示异步任务状态;请等待任务结束,不要重复提交同一删除操作。

删除Schema的推荐顺序:IndexLabel、EdgeLabel、VertexLabel、PropertyKey。删除前先停止对目标模型的新写入。

更新和删除:

# 删除边
g.E().hasLabel("knows").drop()

# 删除顶点
g.V(vertexId).property("age", 26).iterate()
g.V(vertexId).outE("knows").drop().iterate()
g.V(vertexId).drop().iterate()

# 删除全量数据
g.E().drop()
g.V().drop()

删除schema:

# 异步清理任务会返回taskId,后续根据该id查询任务进度
graph.schema().edgeLabel("knows").remove()
graph.schema().vertexLabel("person").remove()
graph.schema().propertyKey("name").remove()

查看异步清理任务状态:

graph.task.{taskId}

使用边界与排错

  • 每个AnalyticDB for MySQL集群的数据、Schema和任务相互隔离;客户无需增加隔离字段。

  • 对客标准查询语言为Gremlin,不提供Cypher、SQL、Bolt、APOC或Neo4J GDS兼容承诺。

  • 语法或Schema错误应修正语句,不建议直接重试。

  • 限流或繁忙时请降低并发并退避重试。

  • 写入超时后,先按业务ID或返回ID查询确认,再决定是否重试。

需要排查问题时,请提供AnalyticDB for MySQL集群、执行时间、完整Gremlin语句和页面错误信息。

常见问题

是否需要在顶点和边上增加集群或隔离字段?

不需要。AnalyticDB for MySQL自动完成集群级数据隔离。

不同AnalyticDB for MySQL集群可以使用相同Schema名和顶点ID吗?

可以,数据互不影响。

为什么创建了unique约束仍然不能按该字段查询?

unique用于写入唯一性约束;需要按该字段查询时,仍需创建secondary索引。

写入成功后可以立即查询吗?

可以。Schema刚创建或删除时,请以页面显示的任务状态为准。