本文导读

展开导读

文档首页/ 图引擎服务 GES/ API参考/ 业务面API/ 持久化版/ Cypher操作API/ 执行Cypher查询

执行Cypher查询

更新时间：2024-12-03 GMT+08:00

功能介绍

Cypher是一种被广泛使用的声明式图数据库查询语言，使用Cypher语句可以查询GES中的数据，并返回结果。当前的Cypher实现中使用了图的统计信息，目前Cypher查询编译过程中使用了基于label的点边索引，如需正常使用Cypher，请先参考Cypher预置条件构建索引。

URI

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

表1 路径参数
参数	是否必选	类型	说明
project_id	是	String	项目ID。获取方法请参见获取项目ID。
graph_name	是	String	图名称。

请求示例

执行Cypher查询，Cypher语句为match (n) return n limit 1，返回的结果样式是每个元素对应该行的一个字段。

POST http://{SERVER_URL}/ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=execute-cypher-query
{
       "statements": [{
              "statement": "match (n) return n limit 1",
              "parameters": {},
              "resultDataContents": ["row"],
              "includeStats": false
       }]
}

请求参数

表2 Body参数说明
参数	是否必选	类型	说明
statements	是	List	statements为一个语句组，包含一到多条语句。其中每个元素的格式如表 statements参数说明。

表3 statements参数说明
参数	是否必选	类型	说明
statement	是	String	Cypher语句。
parameters	是	Object	Cypher语句参数，在进行参数化查询时使用，默认为空。如需使用，请参考参数化查询。
resultDataContents	否	String或List	返回的结果样式，样式可设置一个或多个。可选参数有“row”,”graph”, “raw”(2.2.27版本新增)。
includeStats	否	Boolean	控制返回结果是否携带增删改统计信息的开关，若不设置此字段，默认为不携带。
runtime	否	String	执行器类型，可选值为“map”、“slotted” 、“block”，默认为“map”。slotted执行器自2.3.15版本开始支持，block执行器自2.4.1版本开始支持。
executionMode（2.2.23）	否	String	执行模式。同步执行模式填写“sync”，异步执行填写“async”，不写默认同步执行。异步模式下，获取查询结果参见查询Job状态。
limit（2.2.23）	否	Int	该字段仅在异步模式下生效，表示对异步结果的最大结果数限制，默认值为100000。
transactional	否	Bool	控制Cypher请求是否为事务的。默认为false。更多详细Cypher事务介绍参见Cypher事务。

说明：

在语句前可以添加explain和profile前缀，用于显示查询计划： explain只显示查询计划，不执行语句；profile显示查询计划，并执行语句。
runtime字段说明：与map执行器相比，slotted执行器在语句的计划生成阶段完成了更多的语句数据流分析，在大部分情况下执行速度更快，占用内存更少。
在异步模式（executionMode参数值为async）下，支持cypher查询结果以csv格式导出到文件（GES版本2.3.4及以上支持该功能），详情请参考导出job返回结果到文件(2.2.1)。目前支持下列对象的返回：
1. 点边单值属性、点边id、分组计数结果等值类型。
2. 对于对象类型，目前的版本暂不支持导出，csv中视作空值处理。
Cypher事务（仅持久化版规格有效）：
1. 持久化版规格下Cypher支持事务，用户可以通过设置transactional为true来开启Cypher的事务功能，以保证单条Cypher语句的原子性。对于多条Cypher语句的事务暂不支持。事务的隔离级别为串行化（serializability）。
2. 由于底层存储引擎存在5s的事务时间窗口限制，因此Cypher的事务不可超过5s。对于复杂的查询，比如说多跳，运行时间可能会超过5s，从而触发超时导致提交失败。
  使用Cypher的dbms.killQuery过程可以终止Cypher事务（详见Cypher API-函数和过程），并回滚这条Cypher请求造成的所有改动。

响应参数

表4 响应Body参数说明
参数	类型	说明
results	List	一个List，每个元素是一条Cypher语句的返回结果。
errors	List	一个List，每个元素包含字符串形式的code和message信息。

表5 参数results中各要素说明
参数	类型	说明
columns	List	返回的字段名。
data	List	返回的数据值，每个元素代表一条记录。
stats	Object	返回的增删改统计信息。
plan	Object	如果cypher语句带explain或者profile前缀，则此字段输出查询计划，否则不显示该字段，正常执行查询。profile特性2.3.12版本开始支持。
jobId(2.3.10)	String	请求为异步执行模式下，该字段用于输出异步任务id。
jobType(2.3.10)	Integer	请求为异步执行模式下，该字段用于输出异步任务的类型。

表6 参数data中各要素说明：
参数	类型	说明
row	List	表示具体一行的内容，每个元素对应该行的一个字段，仅当resultDataContents为空或者包含“row”类型时显示。
meta	List	表示该行每个字段的类型信息，仅当resultDataContents为空或者包含“row”类型时显示。
graph	Object	以“graph”样式返回该行信息，仅当resultDataContents包含“graph”类型时显示。
raw(2.2.27)	List	以“raw”样式返回该行信息，仅当resultDataContents包含“raw”类型时显示。

表7 stats各要素响应参数：
参数	类型	说明
contains_updates	Boolean	表示本次查询是否有数据修改。
edges_created	Integer	创建的边数目。
edges_deleted	Int	删除的边数目。
labels_set	Integer	设置的label数目。
properties_set	Integer	设置的属性数目。
vertices_created	Integer	创建的点数目。
vertices_deleted	Integer	删除的点数目。

响应示例

状态码： 200

成功响应示例（同步任务）

Http Status Code: 200
{
    "results": [
        {
            "columns": ["n"],
            "data": [
                {
                    "row": [
                        {
                            "occupation": "artist",
                            "gender": "F",
                            "Zip-code": "98133",
                            "userid": 0,
                            "age": "25-34"
                        }
                    ],
                    "meta": [
                        {
                            "id": "46",
                            "type": "node",
                            "labels": [
                                "user"
                            ]
                        }
                    ]
                }
            ]，
            "stats": {
                "contains_updates": false,
                "edges_created": 0,
                "edges_deleted": 0,
                "labels_set": 0,
                "properties_set": 0,
                "vertices_created": 0,
                "vertices_deleted": 0
             }
        
         }
    ],
    "errors": []
}

状态码： 200

成功响应示例（异步任务）

Http Status Code: 200
{
    "results": [
        {
            "columns": [
                "jobId",
                "jobType"
            ],
            "jobId": "b64a5846-e306-4f87-b0f1-d595ee2a9990",
            "jobType": 1,
            "data": [
                {
                    "row": [
                        "b64a5846-e306-4f87-b0f1-d595ee2a9990",
                        1
                    ],
                    "meta": [
                        null,
                        null
                    ]
                }
            ]
        }
    ],
    "errors": []
}

状态码： 400

失败响应示例

Http Status Code: 400
{
    "results": [],
    "errors": [
        {
            "code": "GES.8904",
            "message": "Label index in vertices is not found."
        }
    ]
}

状态码

返回值	说明
400 Bad Request	请求错误。
401 Unauthorized	鉴权失败。
403 Forbidden	没有操作权限。
404 Not Found	找不到资源。
500 Internal Server Error	服务内部错误。
503 Service Unavailable	服务不可用。

错误码

请参见错误码。

父主题： Cypher操作API

上一篇：Cypher操作API

下一篇：基本操作和兼容性

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在我的云声建议查看反馈及问题处理状态。

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨

智能客服提问云社区提问

执行Cypher查询

功能介绍

URI

请求示例

请求参数

响应参数

响应示例

状态码

错误码

相关文档

意见反馈

文档内容是否对您有帮助？

7*24

备案

专业服务

退订

建议反馈

售前咨询热线

文档反馈