华为云图引擎服务GES对接使用完全指南：从图创建到查询优化

1. 图引擎服务GES概述

图引擎服务（Graph Engine Service，简称GES）是华为云推出的业内首个商用的、拥有自主知识产权的国产分布式原生图引擎。与传统的关系型数据库不同，GES专门针对以关系为基础的图结构数据进行存储、查询和分析，能够高效处理复杂的关系网络数据。

GES广泛应用于社交关系分析、营销推荐、知识图谱、金融风控、信息传播、防欺诈等具有丰富关系数据的场景。在技术架构上，GES提供内存版和持久化版两种产品类型：内存版基于内存存储和计算，最大可支持到百亿边，预置丰富的算法，支持Gremlin和Cypher查询语言；持久化版基于分布式KV数据库做存储和计算，容量无限，有更高的性能，仅支持Cypher查询语言。

2. 使用GES的前置准备

在使用GES服务之前，您需要先完成以下准备工作：

• 注册华为云账号并进行实名认证
• 确保账号状态正常，不能处于欠费或冻结状态
• 了解GES的基本计费模式，根据业务需求选择合适的规格

需要先登录华为云控制台，点击：华为云控制台，还没有账号，点击：注册并关联，已有账号点击：登录后关联

3. 创建图实例

图实例是GES服务中的核心资源，所有的图数据存储和查询分析都基于图实例进行。GES提供了三种创建图的方式：

3.1 自定义创建图

自定义创建是最灵活的创建方式，您可以全面控制图的各项配置参数。进入图引擎服务管理控制台，单击右上角的创建图按钮，进入创建图页面后，需要配置以下核心参数：

• 图名称：4至50个字符，必须以字母开头，只能包含字母、数字或下划线。图创建后不支持修改图名称
• GES软件版本：系统默认当前最新版本
• 虚拟私有云VPC：选择需要创建集群的VPC，若无VPC则需要新建
• 子网：通过子网提供与其他网络隔离的、可以独享的网络资源
• 安全组：为同一个VPC内具有相同安全保护需求的资源提供访问策略
• 公网访问：可选择暂不使用、现在购买或使用已有弹性IP
• 安全模式：开启后访问图实例将进行通讯加密，仅支持HTTPS协议
• 是否支持跨AZ高可用：开启后图实例分布在不同可用区以增强可靠性
• 用途：企业生产支持高可靠高并发，开发学习适合开发者体验

3.2 行业图模板创建

行业图模板创建方式针对特定行业场景提供了预置的图模型和配置，适合快速原型验证和标准场景部署。

3.3 创建动态图

动态图功能将单一视角的静态图转化为多视角的动态图，能够展示在一段时间内点和边随时间变化的轨迹。

4. 导入图数据

图实例创建完成后，需要将数据导入到图中。GES支持通过控制台和API两种方式进行数据导入。

4.1 控制台导入

在图管理页面，选择需要导入数据的图，在操作列选择导入。在弹出的导入提示框中，需要准备三类数据文件：

• 元数据文件：定义图的Schema结构，包括点Label和边Label及其属性
• 点数据集：包含图中所有顶点的数据，CSV格式
• 边数据集：包含图中所有关系的数据，CSV格式

首先单击元数据、边数据集和点数据集后的下载模板按钮，将下载的三个模板放入已有的OBS桶路径下。下载的模板中已包含一份示例电影数据，可直接使用进行测试。

4.2 API导入

GES提供了导入图的REST API，支持更灵活的自动化数据导入：

POST /ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=import-graph

请求体参数说明：

• edgesetPath：边文件目录或边文件名
• edgesetFormat：边数据集格式，当前仅支持csv
• vertexsetPath：点文件目录或点文件名
• vertexsetFormat：点数据集格式，当前仅支持csv
• schemaPath：新增数据的元数据文件OBS路径
• logDir：导入图日志存放目录
• parallelEdge：重复边处理方式，allow允许重复、ignore忽略重复、override覆盖重复
• offline：是否离线导入，true时导入速度较快但图处于锁定状态

请求示例：

POST http://{SERVER_URL}/ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=import-graph
{
  "edgesetPath": "testbucket/demo_movie/edges/",
  "edgesetFormat": "csv",
  "vertexsetPath": "testbucket/demo_movie/vertices/",
  "vertexsetFormat": "csv",
  "schemaPath": "testbucket/demo_movie/incremental_data_schema.xml",
  "logDir": "testbucket/importlogdir"
}

导入操作是异步任务，执行成功后会返回jobId，可以通过查询jobId来跟踪任务执行状态。

5. 图查询与分析

GES提供了图引擎编辑器作为主要的查询分析工具，内置丰富的算法，兼容Gremlin、Cypher和DSL三种查询语言。

5.1 Cypher查询语言

Cypher是一种被广泛使用的声明式图数据库查询语言，对于Neo4j用户来说迁移成本极低。Cypher查询编译过程中使用了基于label的点边索引。如需正常使用Cypher，需要同时添加点label索引和边label索引。

Cypher支持的常用操作：

// 查点
match (n) return n

// 查边
match (n)-[r]->(m) return n, r, m

// 查路径
match (n:user)-[r]->(m:movie)-->(s:series) return n,r,m,s

// 过滤查询
match(n:user) where n.userid>=5 return n

// 分组聚集
match(n:movie) return n.genres, count(*)

// 去重
match(n:movie) return distinct n.genres

// 排序
match(n:movie) return n order by n.movieid

// 创建点
create (n:user{userid:1}) return n

// 创建边
match (n:user{userid:15}),(m:movie{movieid:10}) create (n)-[r:rate]->(m)

// 删除点
match (n:user{userid:1}) delete n

// 更改属性
match (n:user{userid:1}) set n.userid=2 return n

Cypher支持的子句包括match、optional match、return、with、where、order by、skip、limit、create、delete、set、unwind、union等。目前暂不支持merge、foreach等操作，暂不支持使用Cypher语句增删索引。

5.2 Gremlin查询语言

Gremlin是Apache Tinkerpop框架中使用的图遍历语言，使用Gremlin可以很方便地对图数据进行查询、修改、局部遍历和属性过滤。

常用Gremlin操作示例：

// 新增点，Label为user，ID为600，age为18-24
g.addV('user').property(id, '600').property('age', '18-24')

// 删除ID为600的点
g.V('600').drop()

// 新增边
g.addV('user').property(id, '501').property('age', '18-24')

5.3 DSL查询语言

GES提供了一种graph DSL查询语言，可以利用DSL来完成对图的查询与计算，帮助用户低成本设计并运行算法。该功能仅支持2.3.14及以上版本的图。

5.4 图算法分析

GES提供了丰富的图算法，包括基础图算法、图分析算法和图指标算法。主要算法包括：

• PageRank：网页排名算法，用于评估节点的重要性
• PersonalRank：个性化PageRank算法
• k-core：k核分解算法
• 最短路径：计算两点之间的最短路径
• 标签传播：社区发现算法
• 三角计数：计算图中的三角形数量
• 关联预测：预测节点之间可能存在的关联

6. GES SDK开发对接

图引擎服务软件开发工具包（GES SDK）是对GES提供的REST API进行的封装，以简化用户的开发工作。GES SDK区分为管理面SDK和业务面SDK：

• 管理面SDK：开源，支持maven、pip等工具下载，支持Java、Python、Go、NodeJs和PHP，支持API Explorer动态生成代码
• 业务面SDK：不开源，只能从GES连接管理界面下载，支持Java和Python

6.1 获取SDK

图实例创建完成后，可以通过连接管理功能下载相应的SDK和驱动。在图引擎管理控制台，左侧导航栏选择连接管理，即可进入下载页面。

6.2 Python SDK使用示例

解压huaweicloud-ges-sdk-xxx.zip后，找到graph-python-sdk-example的Python工程，可以导入到IDE中。找到API对应的样例类，参考API参数说明，修改为业务实际的参数值即可使用。

客户端初始化示例：

from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkges.v1.region.ges_region import GesRegion
from huaweicloudsdkges.v1.ges_client import GesClient

# AK/SK认证
credentials = BasicCredentials(ak, sk)

# 初始化客户端
client = GesClient.new_builder() \
    .with_credentials(credentials) \
    .with_region(GesRegion.CN_NORTH_4) \
    .build()

查询Job状态示例：对创建图、关闭图、启动图、删除图、导入图等异步API命令下发后，会返回jobId，通过jobId查询任务的执行状态。

# 查询Job状态
job_id = "xxx"  # 从异步API返回结果中获取
response = client.show_job(job_id)
print(response)

6.3 Java SDK使用示例

解压huaweicloud-ges-sdk-xxx.zip后，找到graph-java-sdk-example的Maven工程，可以导入到IDE中。执行PageRank算法示例：

public void static executeAlgorithm(GraphClient graphClient) throws ApiException {
    // 设置PageRank算法参数
    Map<String, Object> parameters = new HashMap<>();
    parameters.put("alpha", 0.85);
    parameters.put("convergence", 0.00001);
    parameters.put("max_iterations", 1000);
    
    // 执行算法
    AlgorithmResponse response = graphClient.executeAlgorithm("pagerank", parameters);
    String jobId = response.getJobId();
    // 轮询查询Job状态获取结果
}

7. API调用与认证

调用GES管理面API有两种认证方式：

• Token认证：通过Token认证调用请求。Token在计算机系统中代表令牌，拥有Token就代表拥有某种权限
• AK/SK认证：通过AK（Access Key ID）/SK（Secret Access Key）加密调用请求。推荐使用AK/SK认证，其安全性比Token认证更高

业务面API访问有两种方式：

• 通过ECS访问，且创建ECS的VPC和创建图选定的VPC是同一个。如果安全组选择的是同一个，则可以直接访问
• 如果安全组不是同一个，需要在创建图的安全组开通该ECS的访问限制，即入方向放开80和443端口，出方向放开所有端口

8. 权限管理

GES使用IAM（Identity and Access Management）进行精细化的权限管理。默认情况下，管理员创建的IAM用户没有任何权限，需要将其加入用户组，并给用户组授予策略或角色。

GES预置了以下系统策略：

• GES FullAccess：图引擎服务管理员权限，拥有该权限的用户拥有图引擎服务的全部权限，包括创建、删除、访问、升级等操作。需要同时拥有Tenant Guest、Server Administrator、VPC Administrator权限
• GES Development：图引擎服务开发权限
• GES ReadOnlyAccess：图引擎服务只读权限

基于策略的授权是一种更加灵活的授权方式，能够满足企业对权限最小化的安全管控要求。用户可以通过创建自定义策略，包含GES服务所有权限及GES服务依赖服务的最小权限合集，然后创建用户组并将IAM账号加入用户组中，授予自定义策略。

此外，GES图实例还提供了细粒度权限控制，可对特定Label的特定属性设置遍历（traverse）、读、写权限。

9. 运维监控

GES提供了完善的运维监控能力：

• 通过图实例运维监控功能，用户可以获取图实例的状态以及可用资源数量，深入了解当前实例实时的资源消耗情况
• 监控指标命名空间为SYS.GES
• 用户可以通过云监控服务提供的管理控制台或API接口来检索图引擎服务产生的监控指标和告警信息
• 监控指标包括实例概览指标、边容量使用率（ges002_edge_util）等
• 云监控数据显示的是当前时间5至10分钟前的状态

10. 计费模式

GES提供两种计费模式：

• 按需计费（按小时）：适合短期测试和弹性业务
• 包年包月（预付费实例）：适合长期稳定业务，成本更优

GES支持绑定公网IP，所需费用按照虚拟私有云（VPC）服务的EIP计费规则进行计费；GES在华为云内部网络产生的流量不计费。用户可以通过GES提供的价格计算器快速估算所需规格的费用。

11. 常见问题

问：GES支持哪些查询语言？

答：GES兼容Gremlin、Cypher和DSL三种查询语言。Gremlin适合图遍历操作，Cypher适合声明式查询（尤其方便Neo4j用户迁移），DSL适合低成本设计并运行算法。

问：GES的内存版和持久化版有什么区别？

答：内存版基于内存存储和计算，最大可支持到百亿边，预置丰富算法，支持Gremlin和Cypher查询；持久化版基于分布式KV数据库，容量无限，性能更高，仅支持Cypher查询语言。

问：如何保证GES数据的安全性？

答：可以通过以下方式保障数据安全：开启安全模式使访问仅支持HTTPS协议；使用IAM进行细粒度权限控制，遵循最小权限原则；配置图细粒度权限，对特定Label的特定属性设置访问权限。

问：GES导入数据时出现错误如何排查？

答：首先检查接口传入的参数与给定类型是否一致；检查必选参数是否填写；检查参数是否符合API文档中的规范。如果是网络波动问题建议重试，若继续失败则收集日志反馈给服务支持人员。

问：GES的图创建后能否修改图名称？

答：图创建后不支持修改图名称。创建图时请谨慎设置图名称。

问：如何监控GES图实例的运行状态？

答：可以通过云监控服务查看GES的各项监控指标，包括实例状态、可用资源、实时资源消耗等。监控指标命名空间为SYS.GES，可通过管理控制台或API接口检索。