# 执行Cypher查询 - ExecuteCypherQuery #### 功能介绍 Cypher是一种被广泛使用的声明式图数据库查询语言，使用Cypher语句可以查询GES中的数据，并返回结果。当前的Cypher实现中使用了图的统计信息，目前Cypher查询编译过程中使用了基于label的点边索引，如需正常使用Cypher，请先参考[Cypher预置条件](https://support.huaweicloud.com/api-ges/ges_03_0337.html)构建索引。 #### URI POST /ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=execute-cypher-query 表1路径参数 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释：** 项目编号。获取方法，请参见[获取项目ID](https://support.huaweicloud.com/api-ges/ges_03_0111.html)。 **约束限制：** 不涉及。 **取值范围：** 只能由英文字母和数字组成，且长度为\[1-64\]个字符。 **默认取值：** 不涉及。 | | graph_name | 是 | String | **参数解释：** 图名称。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 请求参数 表2Body参数说明 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | statements | 是 | List | **参数解释：** statements为一个语句组，包含一到多条语句。其中每个元素的格式如[statements参数说明]。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表3statements参数说明 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | statement | 是 | String | **参数解释：** Cypher语句。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | parameters | 否 | Object | **参数解释：** Cypher语句参数，在进行参数化查询时使用，默认为空。 如需使用，请参考[参数化查询](https://support.huaweicloud.com/api-ges/ges_03_0338.html#ges_03_0338__li8383195704410)。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | resultDataContents | 否 | String或List | **参数解释：** 返回的结果样式，样式可设置一个或多个。可选参数有"row","graph", "raw"(2.2.27版本新增)。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | includeStats | 否 | Boolean | **参数解释：** 控制返回结果是否携带增删改统计信息的开关，若不设置此字段，默认为不携带。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | runtime | 否 | String | **参数解释：** 执行器类型。 **约束限制：** 1. slotted执行器自2.3.14版本开始支持。 2. block执行器自2.4.1版本开始支持。 3. 与map执行器相比，slotted执行器和block执行器在语句的计划生成阶段完成了更多的语句数据流分析，在大部分情况下执行速度更快，占用内存更少。 **取值范围：** 可选值为"map"、"slotted"、"block"。 **默认取值：** 默认为"map"。 | | pathMode（2.5.1） | 否 | String | **参数解释：** 可变长多跳的遍历模式，表示可变长多跳时同一条path点边能否重复。 注意：只有参数runtime的值为"block"时，该参数才会生效。 **约束限制：** 不涉及。 **取值范围：** 可选值为"WALK"、"TRAIL"、"ACYCLIC"、"SIMPLE"。 **默认取值：** 默认为"TRAIL"。 | | executionMode（2.2.23） | 否 | String | **参数解释：** 执行模式。 **约束限制：** 不涉及。 **取值范围：** - sync：同步。 - async：异步。 **默认取值：** 默认为"async"，异步返回。 执行模式。同步执行模式填写"sync"，异步执行填写"async"，不写默认同步执行。异步模式下，获取查询结果参见[查询Job状态](https://support.huaweicloud.com/api-ges/ges_03_0037.html)。 | | limit（2.2.23） | 否 | Int | **参数解释：** 该字段仅在异步模式下生效，表示对异步结果的最大结果数限制。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 默认值为100000。 | - 在语句前可以添加explain或profile前缀，用于显示查询计划： - explain只显示查询计划，不执行语句。explain前缀2.2.20版本开始支持。 - profile显示查询计划，并执行语句。profile前缀2.3.12版本开始支持。 - 在异步模式（executionMode参数值为async）下，支持cypher查询结果以csv格式导出到文件（GES版本2.3.4及以上支持该功能），详情请参考[导出job返回结果到文件](https://support.huaweicloud.com/api-ges/ges_03_0172.html)。目前支持下列对象的返回： 1. 点边单值属性、点边id、分组计数结果等值类型。 2. 对于对象类型，目前的版本暂不支持导出，csv中视作空值处理。 - 其中参数pathMode的四种遍历模式解释如下： | 模式 | 含义 | |:---|:---| | WALK | 同一条路径中，点边都可以重复。 | | TRAIL | 同一条路径中，边不可以重复。 | | ACYCLIC | 同一条路径中，点不能重复。 | | SIMPLE | 同一条路径中，除了末端顶点外，中间节点不能重复。 | #### 响应参数 表4响应Body参数说明 | 参数 | 类型 | 说明 | |:---|:---|:---| | results | List | **参数解释：** 每个元素是一条Cypher语句的返回结果。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | errors | 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"类型时显示。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表7stats各要素响应参数： | 参数 | 类型 | 说明 | |:---|:---|:---| | contains_updates | Boolean | **参数解释：** 表示本次查询是否有数据修改。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | edges_created | Integer | **参数解释：** 创建的边数目。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | edges_deleted | Integer | **参数解释：** 删除的边数目。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | labels_set | Integer | **参数解释：** 设置的label数目。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | properties_set | Integer | **参数解释：** 设置的属性数目。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | vertices_created | Integer | **参数解释：** 创建的点数目。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | vertices_deleted | Integer | **参数解释：** 删除的点数目。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 请求示例 执行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 }] } ``` #### 响应示例 **状态码： 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.8901", "message": "No statement provided." } ] } ``` #### 状态码 | 返回值 | 说明 | |:---|:---| | 202 Accepted | 请求已接收，暂未处理。 | | 400 Bad Request | 请求错误。 | | 401 Unauthorized | 鉴权失败。 | | 403 Forbidden | 没有操作权限。 | | 404 Not Found | 找不到资源。 | | 500 Internal Server Error | 服务内部错误。 | | 503 Service Unavailable | 服务不可用。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-ges/ges_03_0110.html)。