更新时间:2024-05-09 GMT+08:00

执行Cypher查询

功能介绍

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-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

服务不可用。

错误码

请参见错误码