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

1. 图引擎服务GES概述

图引擎服务（Graph Engine Service，简称GES）是华为云自主研发的、业内首个商用的国产分布式原生图引擎。它专门针对以关系为基础的图结构数据进行高效的查询与分析，广泛应用于社交关系分析、营销推荐、信息传播、金融风控、防欺诈等具有丰富关系数据的场景。GES使用自研的EYWA内核，兼容Gremlin、Cypher和DSL三种查询语言，并提供了开放的API接口。

与传统的关系型数据库相比，图引擎在处理复杂关联关系时具有天然的优势。例如在社交网络中查询用户的好友的好友、在金融风控中追踪资金流转路径、在知识图谱中探索实体间的多跳关系等场景下，GES能够以极高的效率完成这些在关系型数据库中需要多次JOIN操作才能实现的查询。GES在图数据库领域的性能表现卓越，曾在国际标准测试中每秒并发查询数量突破4万次操作。

使用GES服务之前，您需要先注册华为云账号并进行实名认证。同时需要确保账号状态正常，不能处于欠费或冻结状态。

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

2. 权限配置与准备工作

在使用GES服务之前，需要通过统一身份认证服务（IAM）进行精细的权限管理。默认情况下，管理员创建的IAM用户没有任何权限，需要将用户加入用户组并授予相应的策略或角色。

2.1 GES权限策略

GES提供了以下几种预置的权限策略：

• GES FullAccess：图引擎服务管理员权限，拥有该权限的用户拥有图引擎服务的全部权限，包括创建、删除、访问、升级等操作。
• GES Development：图引擎服务使用权限，拥有该权限的用户可以执行除了创建图、删除图、变更规格、扩副本以外的所有操作。
• GES ReadOnlyAccess：只读权限，仅能查看图信息而无法进行创建、修改等操作。

您可以根据实际业务需求，为不同角色的员工分配不同的权限。例如，开发人员可以被授予GES Development权限以便进行图数据的查询和分析，而运维人员则需要GES FullAccess权限来管理图的整个生命周期。

2.2 创建用户并授权

使用IAM进行权限配置的基本流程如下：

1. 在IAM控制台创建用户组，并授予GES服务相应的权限策略。
2. 在IAM控制台创建用户，并将其加入上一步创建的用户组中。
3. 使用新创建的用户登录控制台，切换至授权区域验证权限是否生效。

验证权限时，可以在服务列表中选择图引擎服务，尝试创建一个新图。如果无法创建（假设权限仅包含GES ReadOnlyAccess），则说明权限配置正确。此外，GES还支持图实例级别的细粒度权限控制，可对特定Label的特定属性设置遍历、读、写权限。

3. 创建图实例

图实例是GES服务中进行图数据存储和查询的基本单元。创建图是使用GES服务的第一步。GES提供了三种创建图的方式：

3.1 自定义创建图

这是系统默认使用的创建方式。您可以直接使用系统默认的创图方式，也可以根据业务需求自定义配置图的规格、存储类型、副本数等参数。自定义创建图适合对图引擎有深入了解、需要精细控制图配置的用户。

3.2 行业图模板创建图

GES提供了预置的行业图模板，您可以直接使用模板快速创建图。这种方式适合需要快速搭建图应用、对图结构已有标准模板的场景。

3.3 创建动态图

动态图功能将单一视角的静态图转化为多视角的动态图，可以展示在一段时间内点、边随时间变化的轨迹。动态图适合需要分析时序变化关系的场景，如社交网络中的关系演变、金融交易的时间序列分析等。

创建图的具体操作步骤如下：

1. 登录华为云账号，进入图引擎服务管理控制台。
2. 单击右上角的创建图按钮，进入创建图页面。
3. 选择区域，即集群工作区域，可在页面左上角下拉栏选择。
4. 根据需要选择创建方式，填写图名称、选择规格等配置信息。
5. 确认配置后提交创建请求。

4. 元数据管理

元数据是图数据结构定义的描述文件，它定义了图中点（Vertex）和边（Edge）的类型（Label）及其属性（Property）。在使用GES导入图数据之前，需要先准备并导入元数据。

4.1 元数据的导入方式

GES支持从两种来源导入元数据：

• 从本地导入：将本地准备好的元数据XML文件直接上传到图引擎服务中。
• 从OBS导入：提前将准备好的元数据文件上传至OBS桶中，然后从OBS导入到图引擎服务中使用。

无论采用哪种方式，都需要确保元数据文件格式符合GES的要求。元数据文件定义了图中点边数据的结构，包括Label名称、属性名称和属性类型等信息。

导入元数据的操作步骤如下：

1. 在图引擎管理控制台，单击左侧导航栏的元数据管理。
2. 在元数据管理页面，单击左上角的导入按钮。
3. 在导入页面，选择从本地或从OBS中导入元数据。
4. 选择完成后单击确定，导入的元数据会显示在元数据管理页面中。

5. 图数据导入

元数据导入完成后，就可以将图数据（点数据和边数据）导入到图实例中。GES提供了多种数据导入方式，以适应不同的数据源和场景需求。

5.1 数据格式要求

GES要求导入的图数据以CSV格式存储，其中点数据文件和边数据文件需要分别准备。CSV文件中需要包含与元数据定义相匹配的列，每行代表一个点或一条边。数据文件的分隔符可以是逗号、空格、Tab键或用户自定义的分隔符。

5.2 数据迁移功能

GES的数据迁移功能提供了一键式从常见的关系型数据库（MySQL、Oracle、神通MPP）以及大数据组件（DWS、Hive）将数据导入到图实例的能力。用户只需要将原始数据预处理成GES所需要的点边表，就可以通过界面化操作将这些点边表导入到图实例。

这一功能省去了之前繁琐的生成元数据、导出成CSV、上传到OBS、从OBS导入到GES等复杂的中间步骤，极大地方便了用户数据入图的操作。通过DataArts Studio的Import GES节点，也可以将OBS桶中的文件导入到GES的图中。

5.3 增量导入

在创建图完成后可以导入图数据，或者当您需要新增图数据时，可以利用导入功能进行增量导入。增量导入允许用户在已有图数据的基础上追加新的点或边，而不需要重新导入全量数据，这对于需要持续更新图数据的业务场景非常实用。

6. 连接管理与SDK下载

图实例创建完成后，需要通过连接管理功能获取连接信息并下载相应的SDK和驱动。

6.1 获取连接信息

在图引擎管理控制台的左侧导航栏选择连接管理，进入连接管理页面。选择已创建的图实例名称，可以查看到以下连接信息：

• 内网访问地址：同一私有网络内的弹性云服务器可以通过内网访问地址连接当前图实例。
• 公网访问地址（弹性IP）：可以从互联网访问图实例。同时支持图实例弹性IP的解绑与绑定。
• JDBC连接字符串（内网）：当JDBC驱动执行机器和图实例处于同一私有网络时使用。
• JDBC连接字符串（公网）：当JDBC驱动执行机器可以通过互联网访问图实例（已绑定弹性IP）时使用。

6.2 下载SDK和驱动

在连接管理页面，可以下载SDK和驱动程序：

• 业务面SDK：SDK是对业务面API的封装，推荐使用业务面SDK访问GES图实例。业务面SDK支持Java和Python两种编程语言。
• Cypher-JDBC驱动：针对Cypher API访问，推荐使用Cypher-JDBC驱动。

下载时需要选择集群所支持的CPU架构，目前支持X86计算和ARM架构。下载完成后解压SDK压缩包，其中包含完整的代码示例工程。

7. 业务面SDK开发实战

GES的业务面SDK是对GES提供的REST API进行的封装，用户直接调用GES SDK提供的接口函数即可实现使用GES服务业务能力的目的。SDK支持Java和Python两种语言。

7.1 Java SDK开发

解压huaweicloud-ges-sdk-xxx.zip后，可以找到一个名为graph-java-sdk-example的Maven工程，这是GES API对应的Java SDK代码示例。将该工程导入到IDE中，修改API参数即可进行调试。

客户端初始化

Java SDK的客户端初始化需要配置以下参数：

• 图名称（graphName）：在GES控制台的图管理页面获取。
• 图访问地址（graphEndPoint）：分为内网访问地址和公网访问地址，根据需要选择。
• AK/SK认证信息：在华为云控制台我的凭证中创建访问密钥获取。

客户端初始化的参数定义在GraphClientUtils类中，选择不同的认证方式填写参数即可。GES默认仅主节点响应，如需使用从节点响应，可在初始化请求时设置requestType参数。requestType取值为read时请求负载均衡发送到主从节点，取值为slave时请求仅发送到从节点。

Java SDK代码示例

以下是一个使用Java SDK执行Cypher查询的完整示例：

// 导入必要的包
import com.huawei.ges.graph.sdk.v1.GraphClient;
import com.huawei.ges.graph.sdk.v1.model.ExecuteCypherQueryRequest;
import com.huawei.ges.graph.sdk.v1.model.ExecuteCypherQueryResponse;
import com.huawei.ges.graph.sdk.v1.examples.base.Base;

public class ExecuteCypherQuerySample {
    public static void main(String[] args) {
        try {
            // 1. 初始化客户端
            // 从Base类中获取不同认证方式的客户端实例
            GraphClient client = Base.getGraphClientWithAkSk(
                \"your-ak\",           // Access Key
                \"your-sk\",           // Secret Key
                \"cn-north-4\",        // Region Code
                \"your-graph-name\",   // 图名称
                \"your-graph-endpoint\" // 图访问地址
            );
            
            // 2. 构建Cypher查询请求
            ExecuteCypherQueryRequest request = new ExecuteCypherQueryRequest();
            // Cypher查询语句：匹配所有节点，返回前10个
            request.setCypherQuery(\"MATCH (n) RETURN n LIMIT 10\");
            
            // 3. 执行查询
            ExecuteCypherQueryResponse response = client.executeCypherQuery(request);
            
            // 4. 处理查询结果
            System.out.println(\"查询结果: \" + response.getResult());
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

代码样例文件路径为com.huawei.ges.graph.sdk.v1.examples.querylanguage，该路径下存在名为QueryLanguageMain.java的Main文件用于调试。

7.2 Python SDK开发

解压huaweicloud-ges-sdk-xxx.zip后，可以找到一个名为graph-python-sdk-example的Python工程。将该工程导入到IDE中即可进行开发调试。

Python SDK代码示例

以下是一个使用Python SDK执行Cypher查询的完整示例：

# 导入必要的模块
from com.huawei.ges.graph.sdk.v1.examples.base import Base
from com.huawei.ges.graph.sdk.v1.model.execute_cypher_query_request import ExecuteCypherQueryRequest

def execute_cypher_query():
    try:
        # 1. 初始化客户端
        # 使用AK/SK认证方式初始化客户端
        client = Base.get_graph_client_with_ak_sk(
            ak=\"your-ak\",
            sk=\"your-sk\",
            region_code=\"cn-north-4\",
            graph_name=\"your-graph-name\",
            graph_endpoint=\"your-graph-endpoint\"
        )
        
        # 2. 构建Cypher查询请求
        request = ExecuteCypherQueryRequest()
        # Cypher查询语句：查询所有用户节点及其好友关系
        request.cypher_query = \"MATCH (u:User)-[:FRIEND]->(f:User) RETURN u, f LIMIT 20\"
        
        # 3. 执行查询
        response = client.execute_cypher_query(request)
        
        # 4. 处理查询结果
        print(\"查询结果:\", response.result)
        
    except Exception as e:
        print(\"执行查询失败:\", e)

if __name__ == \"__main__\":
    execute_cypher_query()

Python SDK的代码样例文件路径为com.huawei.ges.graph.sdk.v1.examples.querylanguage，文件名为ExecuteCypherQuerySample.py。包路径com.huawei.ges.graph.sdk.v1.examples.base下的Base.py中提供了不同认证方式的客户端初始化样例。

8. 图查询语言详解

GES支持三种图查询语言：Gremlin、Cypher和DSL。用户可以根据使用习惯和业务场景选择合适的查询语言。

8.1 Gremlin查询

Gremlin是Apache TinkerPop框架中使用的图遍历语言，使用Gremlin可以很方便地对图数据进行查询，进行图的修改、局部遍历和属性过滤等。Gremlin是一种函数式、流式的查询语言，适合进行复杂的图遍历操作。

在图引擎编辑器中，可以切换到Gremlin查询模式，输入Gremlin语句执行查询操作。以下是一些常用的Gremlin查询示例：

// 查询ID为'1'的顶点
g.V('1')

// 查询所有标签为'User'的顶点
g.V().hasLabel('User')

// 查询ID为'1'的顶点的所有出边
g.V('1').outE()

// 查询ID为'1'的顶点通过'FRIEND'边关联的顶点
g.V('1').out('FRIEND')

执行Gremlin查询时，可以通过POST请求调用API，请求体中使用command参数指定Gremlin语句。

8.2 Cypher查询

Cypher是一种被广泛使用的声明式图数据库查询语言。使用Cypher语句可以查询和修改GES中的数据并返回结果。Cypher采用类似SQL的声明式语法，非常方便Neo4j用户迁移到GES。

Cypher预置条件

Cypher查询编译过程中使用了基于Label的点边索引。第一次使用Cypher查询时，需要单击结果展示区右上角的建索引按钮。如需正常使用Cypher，请先参考Cypher预置条件构建索引。

Cypher查询示例

以下是一些常用的Cypher查询语句示例：

// 查询所有节点，返回前10个
MATCH (n) RETURN n LIMIT 10

// 查询标签为User的节点
MATCH (u:User) RETURN u

// 查询用户及其好友关系
MATCH (u:User)-[:FRIEND]->(f:User) RETURN u, f

// 查询特定用户的二度好友
MATCH (u:User {id: '1001'})-[:FRIEND*2]->(fof:User) 
RETURN DISTINCT fof

// 查询用户的好友数量
MATCH (u:User)-[:FRIEND]->(f:User) 
RETURN u.id, COUNT(f) AS friendCount

执行Cypher查询的API请求示例如下：

POST /ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=execute-cypher-query
{
    \"cypher\": \"MATCH (n) RETURN n LIMIT 1\"
}

8.3 DSL查询

GES提供了一种graph DSL查询语言，可以利用DSL来完成对图的查询与计算，帮助用户低成本设计并运行算法。DSL算法详细介绍请参考DSL语法介绍。DSL查询功能仅支持2.3.14及以上版本的图。执行DSL算法的API请求格式如下：

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

9. 查询性能优化

图查询的性能直接影响到业务系统的响应速度。GES提供了多种性能优化手段，帮助用户提升查询效率。

9.1 参数化查询

参数化查询是提升Cypher查询性能的重要手段。参数化查询可以使得不同的用户输入使用同一条参数化查询语句执行，能够高效利用数据库查询缓存，节省查询编译时间，从而提升查询性能。

以下是一个参数化查询的示例：

// 使用参数化查询
MATCH (u:User {id: $userId})-[:FRIEND]->(f:User)
RETURN f

在实际使用中，将userId作为参数传递给查询语句，GES可以缓存编译后的查询计划，对于大量相似的查询请求，性能提升非常显著。

9.2 索引优化

Cypher查询编译过程中使用了基于Label的点边索引。合理使用索引可以大幅提升查询性能。对于经常作为查询条件的属性，建议创建相应的索引。GES提供了索引管理功能，用户可以通过API创建、查询和删除索引。

9.3 慢查询识别与终止

对于执行时间过长的慢查询，GES提供了查询终止功能。用户可以首先使用listQueries查询出当前Cypher语句的queryId，然后把queryId传入killQuery中终止慢查询。查看当前主节点上的实时请求的API如下：

GET /ges/v1.0/{project_id}/graphs/{graph_name}/om/real-time-queries

该接口当前仅返回正在运行的Cypher查询。

9.4 读写分离

GES支持主从节点架构，默认仅主节点响应请求。通过设置requestType参数可以实现读写分离：

• requestType取值为read时，请求负载均衡发送到主从节点。
• requestType取值为slave时，请求仅发送到从节点。

当前只有内存版图的读请求支持设置requestType参数。通过合理配置读写分离，可以有效降低主节点的负载，提升整体查询吞吐量。

10. 监控与运维

GES提供了多维度的运维监控接口，保障图实例的平稳运行。该功能收集、监控和分析图实例使用的磁盘、网络、操作系统指标以及集群关键性能指标。

用户可以通过GES管理控制台或API接口来检索图引擎服务产生的监控指标和告警信息。监控指标的命名空间为SYS.GES。主要监控维度包括：

• 磁盘使用率与IO性能
• 网络流量与带宽
• 操作系统资源使用情况
• 集群关键性能指标（QPS、响应时间等）

通过监控数据，用户可以及时发现潜在的性能瓶颈和异常情况，保障图服务的稳定运行。

11. 常见问题与解答

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

答：GES兼容三种查询语言：Gremlin（Apache TinkerPop框架的图遍历语言）、Cypher（声明式图数据库查询语言，方便Neo4j用户迁移）和DSL（GES自研的图查询语言）。

问：如何获取GES的连接地址？

答：登录GES管理控制台，在左侧导航栏选择连接管理，选择已创建的图实例，即可查看内网访问地址、公网访问地址（弹性IP）以及JDBC连接字符串。

问：第一次使用Cypher查询时需要注意什么？

答：第一次使用Cypher查询时，需要先构建基于Label的点边索引。在GES图编辑器的结果展示区右上角单击建索引按钮即可完成。否则Cypher查询可能无法正常执行。

问：GES SDK支持哪些编程语言？

答：业务面SDK目前支持Java和Python两种编程语言。管理面SDK支持Java、Python、Go、NodeJs和PHP等更多语言。用户可以从GES连接管理界面下载对应的SDK。

问：如何优化GES的查询性能？

答：可以从以下几个方面优化查询性能：使用参数化查询利用查询缓存、为常用查询属性创建索引、通过requestType参数配置读写分离、及时终止慢查询。

问：GES如何导入数据？

答：GES支持多种数据导入方式：通过控制台上传CSV格式的点边数据文件、使用数据迁移功能从MySQL/Oracle/DWS/Hive等数据源一键导入、通过DataArts Studio的Import GES节点导入OBS中的数据。