执行事务Cypher
功能介绍
执行事务Cypher。
URI
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
project_id |
是 |
String |
项目ID。获取方法请参见获取项目ID。 |
graph_name |
是 |
String |
图名称。 |
commit |
是 |
String |
事务ID,通过创建事务接口获取。 |
请求参数
参数 |
是否必选 |
类型 |
说明 |
---|---|---|---|
statements |
是 |
List |
statements为一个语句组,包含一到多条语句。其中每个元素的格式如表 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。 |
![](https://support.huaweicloud.com/api-ges/public_sys-resources/note_3.0-zh-cn.png)
- 在语句前可以添加explain和profile前缀,用于显示查询计划: explain只显示查询计划,不执行语句;profile显示查询计划,并执行语句。
- runtime字段说明:与map执行器相比,slotted执行器在语句的计划生成阶段完成了更多的语句数据流分析,在大部分情况下执行速度更快,占用内存更少。
- 在异步模式(executionMode参数值为async)下,支持cypher查询结果以csv格式导出到文件(GES版本2.3.4及以上支持该功能),详情请参考导出job返回结果到文件(2.2.1)。目前支持下列对象的返回:
- 点边单值属性、点边id、分组计数结果等值类型。
- 对于对象类型,目前的版本暂不支持导出,csv中视作空值处理。
- Cypher事务(仅持久化版规格有效):
- 持久化版规格下Cypher支持事务,用户可以通过设置transactional为true来开启Cypher的事务功能,以保证单条Cypher语句的原子性。对于多条Cypher语句的事务暂不支持。事务的隔离级别为串行化(serializability)。
- 由于底层存储引擎存在5s的事务时间窗口限制,因此Cypher的事务不可超过5s。对于复杂的查询,比如说多跳,运行时间可能会超过5s,从而触发超时导致提交失败。
使用Cypher的dbms.killQuery过程可以终止Cypher事务(详见Cypher API-函数和过程), 并回滚这条Cypher请求造成的所有改动。
响应参数
参数 |
类型 |
说明 |
---|---|---|
results |
List |
一个List,每个元素是一条Cypher语句的返回结果。 |
errors |
List |
一个List,每个元素包含字符串形式的code和message信息。 |
参数 |
类型 |
说明 |
---|---|---|
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 |
请求为异步执行模式下,该字段用于输出异步任务的类型。 |
参数 |
类型 |
说明 |
---|---|---|
row |
List |
表示具体一行的内容,每个元素对应该行的一个字段,仅当resultDataContents为空或者包含“row”类型时显示。 |
meta |
List |
表示该行每个字段的类型信息,仅当resultDataContents为空或者包含“row”类型时显示。 |
graph |
Object |
以“graph”样式返回该行信息,仅当resultDataContents包含“graph”类型时显示。 |
raw(2.2.27) |
List |
以“raw”样式返回该行信息,仅当resultDataContents包含“raw”类型时显示。 |
参数 |
类型 |
说明 |
---|---|---|
contains_updates |
Boolean |
表示本次查询是否有数据修改。 |
edges_created |
Integer |
创建的边数目。 |
edges_deleted |
Int |
删除的边数目。 |
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}/transaction/{commit} { "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-d595ee2a9910", "jobType": 1, "data": [ { "row": [ "b64a5846-e306-4f87-b0f1-d595ee2a9910", 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 |
服务不可用。 |
错误码
请参见错误码。