文档首页 > > API参考> 业务面API>

Cypher操作API(2.2.16公测)

Cypher操作API(2.2.16公测)

分享
更新时间:2021/04/07 GMT+08:00

功能介绍

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

URL

  • URI 格式
    POST /ges/v1.0/{projectId}/graphs/{graphName}/action?action_id=execute-cypher-query
  • 参数说明
    表1 URI参数说明

    参数

    是否必选

    类型

    说明

    projectId

    String

    项目编号,用于资源隔离。

    graphName

    String

    图名称。

请求

  • 请求样例
POST http://{SERVER_URL}/ges/v1.0/{projectId}/graphs/{graphName}/action?action_id=execute-cypher-query
{
       "statements": [{
              "statement": "match (n) return n limit 1",
              "parameters": {},
              "resultDataContents": ["row"],
              "includeStats": false
       }]
}
  • 参数说明
    表2 Body参数说明

    参数

    是否必选

    类型

    说明

    statements

    List

    statements为一个语句组,包含一到多条语句。其中每个元素的格式如表 statement参数说明

    表3 statement参数说明

    参数

    是否必选

    类型

    说明

    statement

    String

    Cypher语句。

    parameters

    Json

    Cypher语句参数,在进行参数化查询时使用,默认为空。

    如需使用,请参考参数化查询

    resultDataContents

    String或List

    返回的结果样式,可选参数有“row”,”graph”两种样式可选,一次可返回多个样式。

    includeStats

    Boolean

    控制返回结果是否携带增删改统计信息的开关,若不设置此字段,默认为不携带。

响应

  • 要素说明
    表4 要素说明

    参数

    是否必选

    类型

    说明

    results

    List

    一个List,每个元素是一条Cypher语句的返回结果。

    errors

    List

    一个List,每个元素包含字符串形式的code和message信息。

    表5 参数results中各要素说明

    参数

    是否必选

    类型

    说明

    columns

    List

    返回的字段名。

    data

    List

    返回的数据值,每个元素代表一条记录。

    stats

    Json

    返回的增删改统计信息

    plan

    Json

    如果cypher语句带explain前缀,则此字段输出查询计划,否则不显示该字段,正常执行查询。

    表6 参数data中各要素说明:

    参数

    是否必选

    类型

    含义

    row

    List

    表示具体一行的内容,每个元素对应该行的一个字段,仅当resultDataContents为空或者包含“row”类型时显示。

    meta

    List

    表示该行每个字段的类型信息,仅当resultDataContents为空或者包含“row”类型时显示。

    graph

    Json

    以“graph”样式返回该行信息,仅当resultDataContents包含“graph”类型时显示。

  • 请求成功样例
    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": []
    }
    
    表7 stats各要素响应参数:

    参数

    是否必选

    类型

    含义

    contains_updates

    Boolean

    表示本次查询是否有数据修改

    edges_created

    Integer

    创建的边数目

    edges_deleted

    Int

    删除的边数目

    labels_set

    Integer

    设置的label数目

    properties_set

    Integer

    设置的属性数目

    vertices_created

    Integer

    创建的点数目

    vertices_deleted

    Integer

    删除的点数目

  • 请求失败样例
    Http Status Code: 400
    {
        "results": [],
        "errors": [
            {
                "code": "GES.8904",
                "message": "Label index in vertices is not found."
            }
        ]
    }

返回值

  • 正常

200

  • 异常
    表8 异常返回值说明

    返回值

    说明

    400 Bad Request

    请求错误。

    401 Unauthorized

    鉴权失败。

    403 Forbidden

    没有操作权限。

    404 Not Found

    找不到资源。

    500 Internal Server Error

    服务内部错误。

    503 Service Unavailable

    服务不可用。

Cypher预置条件

当前的Cypher查询编译过程中使用了基于label的点边索引,如需正常使用Cypher,请使用新建索引API构建索引,示例如下:

  • 点label索引添加命令示例
    POST http://{SERVER_URL}/ges/v1.0/{projectId}/graphs/{graphName}/indices
    {
            "indexName": "cypher_vertex_index",
            "indexType": "GlobalCompositeVertexIndex",
            "hasLabel": "true",
            "indexProperty": []
    }
  • 边label索引添加命令示例
    POST http://{SERVER_URL}/ges/v1.0/{projectId}/graphs/{graphName}/indices
    {
            "indexName": "cypher_edge_index",
            "indexType": "GlobalCompositeEdgeIndex",
            "hasLabel": "true",
            "indexProperty": []
    }
    1. 需要同时添加两个索引(点label索引和边label索引)才能正常使用Cypher查询。
    2. 不需要构建的情况:如果图中已经存在hasLabel为true, indexProperty为空的点索引或边索引,则不需要重复构建。
    3. 添加索引API为异步接口,查询索引是否添加成功,请使用查询Job状态API

基本操作

操作名

Cypher语句

查点

match (n) return n

查边

match (n)-[r]->(m) return n, r, m

查路径

match (n:user)-[r]->(m:movie)-->(s:series) return n,r,m,s

过滤查询

match(n:user) where n.userid>=5 return n

分组聚集

match(n:movie) return n.genres, count(*)

去重

match(n:movie) return distinct n.genres

排序

match(n:movie) return n order by n.movieid

创建点

create (n:user{userid:1}) return n

创建边

match (n:user{userid:15}),(m:movie{movieid:10}) create (n)-[r:rate]->(m)

删除点

match (n:user{userid:1}) delete n

更改标签

match (n:user{userid:1}) set n:movie return n

更改属性

match (n:user{userid:1}) set n.userid=2 return n

Cypher实现的兼容性

  • Cypher支持的子句列表

    Cypher实现了若干子句,通过对子句进行组合可以实现丰富的查询语义,进而完成点边过滤、多跳查询、排序去重、分组聚集等诸多能力。目前GES支持的Cypher子句如下:

    表9 Cypher支持的子句清单

    子句

    支持情况

    举例

    match

    部分支持

    match (n:movie) return n

    return

    支持

    return [1,2,3] as p

    with

    支持

    match (n) with labels(n) as label, count(*) as count

    where count > 10 return *

    where

    支持

    match (n:movie) where n.movieid > 10 return n

    order by

    支持

    match (n:movie) return n order by n.genres

    skip

    支持

    match (n:movie) return n order by n.genres skip 5

    limit

    支持

    match (n:movie) return n order by n.genres skip 5 limit 10

    create

    支持

    create (n:user{_ID_: 'Jack' }) return n

    delete

    支持

    match (n:movie)<-[r]-(m:user) delete r

    set

    支持

    match (n:user{userid:0}) set n.gender='M' return n

    call procedures

    支持

    call db.schema()

    unwind

    支持

    unwind [1, 2, 3] as p return p

    1. 目前暂不支持union、merge、foreach、optional等操作,暂不支持使用Cypher语句增删索引,后续会逐渐开放支持。
    2. 由于GES的元数据不是Schema Free的,点边label属性等有严格的限制,因此不支持Remove操作。
    3. Order by子句不支持List类型的排序,当属性值的Cardinality不为single时,排序结果未知。
  • 参数化查询支持

    Cypher支持参数化的查询。通过把查询语句中的数值、字符串等值类型提取为参数,加速查询的编译时间,提高查询速度。

    以下提供几种参数化查询的示例:

    • 参数化查询请求示例1:
      POST http://{SERVER_URL}/ges/v1.0/{projectId}/graphs/{graphName}/action?action_id=execute-cypher-query
      {
               "statements": [{
                         "statement": " match (n:user) where n.occupation = $occupation return n",
                         "parameters": {
                               "occupation" : "artist"
                          },
                         "resultDataContents": ["row"]
               }]
      }
    • 参数化查询请求示例2:
      POST http://{SERVER_URL}/ges/v1.0/{projectId}/graphs/{graphName}/action?action_id=execute-cypher-query
      {
               "statements": [{
                         "statement": " match (n:user {`Zip-code`:'98133'}) set n = $props return n",
                         "parameters": {
                                 "props": {
                                 "gender": "M",
                                 "age": "56+"
                              }
                          },
                         "resultDataContents": ["row"]
               }]
      }

    参数化查询不适用于以下场景,下列查询语句均无法正常执行:

    • 属性键值,如:match (n) where n.$param = 'something'
    • 点边标签,如:match (n:user) set n:$code
  • 数据类型支持

    GES目前支持char、char_array、float、double、Boolean、long、Integer、date、enum、string共10种数据类型,布尔型和数值型在Cypher语法中都能得到支持,其他类型和Cypher存在如下的映射关系,在GES内部实现了类型的转换:

    表10 GES和Cypher的类型映射关系

    GES类型

    Cypher类型

    备注

    char

    String

    -

    char_array

    String

    -

    string

    String

    -

    enum

    String

    由于Cypher语法中未提供枚举相关的语法,在Cypher查询时enum作为String进行输出,使用Cypher设置属性时对于不在枚举列表中的值会设置失败。

    date

    Temporal

    目前支持Date按GES的日期格式输入和输出,暂不支持调用Cypher日期函数输入日期。

    表11 Cypher特殊类型支持情况

    类型

    支持情况

    查询举例 & 备注

    Node

    支持

    match (n) return n limit 10

    Relationship

    支持

    match (n)-[r]->(m) return r limit 10

    List

    支持

    return [1,2,3] as li

    Map

    支持

    match (n)-->(m) return {start:id(n), end:id(m)}

    Path

    支持

    match p=(n1)-[:friends*1..2]-(n2) return p limit 10

    Point、Spatial

    暂不支持

    -

    表 Cypher特殊类型支持情况中提到的特殊类型,其中除了List用于匹配GES中的多值属性外,其他类型均无法通过set语句设为点边上某个属性的值。

  • 表达式

    Cypher查询的where子句支持多种的表达式,可以组合成丰富的过滤条件,目前支持的表达式如下:

    运算类型

    表达式

    举例&备注

    逻辑运算

    and

    match (n:user) where n.age='Under 18' and n.gender='F' return n

    or

    match(n:user) where n.`Zip-code`='22181' or n.userid=6 return n

    not

    match(n:movie) where not n.genres contains 'Drama' return n

    空值判断

    is null

    match (n) where n.userid is null return n

    is not null

    match (n) where n.userid is not null return n

    比较运算

    >,>=,<,<=,=,<>

    match(n:user) where n.userid>=5 return n

    字符串比较

    starts with

    match(n:movie) where n.genres starts with 'Comedy' return n

    ends with

    match(n:movie) where n.genres ends with 'Drama' return n

    contains

    match(n:movie) where n.genres contains 'Drama' return n

    List相关运算

    in

    match(n:student) where 'math' in n.courses return n

    []运算符

    match(n:user) return n[' userid']

    with [1, 2, 3, 4] as list return list[0]

    with [1, 2, 3, 4] as list return list[0..1]

    match p=(n)-->(m) return [x in nodes(p) where x.gender='F'|id(x)]

    Cypher查询的where子句暂不支持case表达式、算数运算符、正则匹配等。

  • 函数和过程
    • 函数

    在分组聚集、点边操作时,cypher支持一系列的函数,目前支持的函数如下所示:

    类别

    函数名

    举例

    聚集函数

    count

    match (n) return count(*)

    match (n) return count(n.userid)

    一般函数

    id

    match (n) return id(n)

    labels

    match (n) return labels(n)

    type

    match(n)-[r]->(m) return type(r)

    nodes

    match p=(n)-[:friends*1..2]->(m) return nodes(p)

    relationships

    match p=(n)-[:friends*1..2]->(m) return relationships(p)

    head

    with [1,2,3,4] as list return head(list)

    last

    with [1,2,3,4] as list return last(list)

    size

    with [1,2,3,4] as list return size(list)

    avg()、max()、min()等聚集函数,以及sin()、cos()等数学函数将在后续版本中陆续开放。

    • 过程

      目前GES 支持如下过程(Procedure):

      名称

      语句

      获取图模式相关信息

      call db.schema()

      获取点label

      call db.labels()

      获取边label

      call db.relationshipTypes()

      查询当前正在执行的Cypher语句

      call dbms.listQueries()

      根据queryId终止某条Cypher语句

      call dbms.killQuery('queryId')

  • 点id的兼容性
    • Cypher添加点时不提供设置id的语法,GES中添加点需要一个字符串型的id,来唯一的标识一个点。为了兼容Cypher语法当前Create语句实现中,通过使用一个特殊的标识符_ID_指定点的id。例如create (n{_ID_:’123456’} )语句,会创建一个id为’123456’的点。
    • 若创建时未指明id,则系统为此点生成一个随机id。

      标识符“_ID_”仅在create语句中支持,match、set等子句均不支持_ID_标识。Match子句中可使用函数id()获取点id。

  • 添加边时的平行边处理策略:

    通过cypher添加边的时候,允许添加重复边,此处的重复边的定义为<源点,终点>相同的两条边。

分享:

    相关文档

    相关产品

文档是否有解决您的问题?

提交成功!非常感谢您的反馈,我们会继续努力做到更好!
反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

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

智能客服提问云社区提问