更新时间:2023-09-21 GMT+08:00

Filtered-query API(2.2.13)

功能介绍

对k跳过程进行逐层过滤,列出满足过滤条件的第k跳节点或边。

URI

POST /ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=filtered-query
表1 路径参数

参数

是否必选

类型

说明

project_id

String

项目ID。获取方法请参见获取项目ID

graph_name

String

图名称。

请求参数

当executionMode为同步时,返回的点个数不能超过10万。

表2 Body参数说明

参数

是否必选

类型

说明

executionMode

String

  • sync:同步
  • async:异步

    默认为“sync ”同步返回。

vertices

Array of Json

查询的起始节点ID列表。

query_type

String

可选:['Default',AllVertices','SimpleEdges',‘Path’]

  • Default为默认模式,即返回用户查询第k跳内容。
  • AllVertices返回用户路径查询k跳以内所有点详情。
  • SimpleEdges返回用户路径查询k跳以内所有边,仅包含边的id和label信息。
  • Path返回用户路径查询的路径信息,即path的集合。

by

Array of Json

用于控制输出字段,当query_type为Default或AllVertices时有效。当前仅支持一层。当字段不存在时,默认为输出所有内容。

edges

Array of Json

查询的起始边列表,与vertices二选一,具体格式见表3

filters

Array of Json

过滤条件列表,数组的每个元素分别对应每一层要做的查询和过滤条件。具体格式见表4

full_path

Boolean

返回的路径信息是否是完整路径,默认为“false”。

  • 为“true”时,返回从起始节点到所有叶子节点的路径。
  • 为“false”时,返回从起始节点到第k层叶子节点的路径。

visualized

Boolean

是否可视化,默认为“false”。在异步模式下:

  • “visualized”“false”时,查询job结果分页返回。
  • “visualized”“true”时,查询job结果不分页。

restricted(2.2.28)

Boolean

是否对输入严格校验,默认为“true”。

  • 在true模式下,如果参数vertices中包含不存在的点,查询会直接退出并报错。
  • 在false模式下,系统会把vertices中不存在的点过滤掉再进行查询任务。
表3 edges元素格式

参数

是否必选

类型

说明

source

String

源节点ID。

target

String

目标节点ID。

index

String

此边在源节点边集合中的索引。

表4 Filters元素格式

参数

是否必选

类型

说明

operator

String

表示要做的查询类型,可选的值有:

  • inV:入点
  • outV:出点
  • bothV:入点和出点
  • vertex:所有节点。第一层filter可用,若起始传入节点,则第一层输出为传入的节点;若起始传入节点为空,则第一层输出为所有节点
  • in:入边
  • out:出边
  • both:入边和出边
  • edge:所有边,仅第一层filter可用,使用方式与vertex类似

后一层的查询操作以前一层的查询结果为输入:

  • 若前一层的结果是点,则对应的操作可以有(inV,outV,bothV,in,out,both)。
  • 若前一层的结果是边,则对应的操作可以有(inV,outV,bothV)。

vertex_filter

String

在“operator”为“ inV”或“outV”或“bothV”时可选,具体格式见表6

edge_filter

String

在“operator”为“in”或“out”或“both”时可选,具体格式见表6

表5 by元素格式

参数

是否必选

类型

说明

id

Boolean

是否输出id。默认为false。

label

Boolean

是否输出label。默认为false。

properties

Boolean

是否输出properties。默认为false。

selectedProperties

Array of String

当properties字段为true时,可以选择输出的属性项。

字段为空时输出所有属性字段。默认为空。

表6 property_filter元素格式

参数

是否必选

类型

说明

leftvalue

String

左值,具体格式见表7

predicate

String

表示过滤类型,支持的操作如下:

比较运算符:

  • =:等于
  • !=:不等于
  • <:小于
  • <=:小于等于
  • >:大于
  • >=:大于等于

逻辑运算:

  • &:与
  • |:或

集合运算:

  • IN/NOTIN:左值与右值是否有交集
  • CONTAIN/NOTCONTAIN:属性值中是否含有右值
  • SUBSET:右值是属性值的子集

匹配运算符:

  • PREFIX:右值是左值的前缀
  • NOTPREFIX:右值不是左值的前缀
  • SUFFIX:右值是左值的后缀
  • NOTSUFFIX:右值不是左值的后缀
  • SUBSTRING:右值是左值的子字符串
  • NOTSUBSTRING:右值不是左值的子字符串
  • FUZZY:模糊匹配
  • REGEX:正则匹配
  • CISUBSTRING:忽略大小写的子字符串

HAS/HASNOT:是否有此属性,仅支持属性过滤,即左值仅支持property_name。

rightvalue

String

右值,具体格式见表8

表7 leftvalue元素格式

参数

是否必选

类型

说明

label_name

String

若过滤“label”,可选“label_name”,值为“labelName”。rightvalue的value字段填具体的label的名称。

property_name

String

若过滤“property”,可选“property_name”,值为属性名称,rightvalue的value字段填属性的值。

id

String

若对节点ID做过滤,可选id,值可不填。

property_filter

String

“predicate”为“&”或者“|”,可在“leftvalue”“rightvalue”中嵌套使用“property_filter”

表8 rightvalue元素格式

参数

是否必选

类型

说明

value

String

  • 若过滤“label”,值为label的名称。
  • 若过滤“property”,值为属性名称。

property_filter

String

“predicate”为“&”或者“|”,可在“leftvalue”“rightvalue”中嵌套使用“property_filter”

表9 predicate使用场景

predicate

label_name

id

property_name

嵌套filter

&

|

HAS/HASNOT

CONTAIN/NOTCONTAIN

SUBSET

是(仅支持右值为集合,若为single,则无过滤作用直接匹配)

IN/NOTIN

是(仅支持右值为集合,若为single,则不匹配)

PREFIX

FUZZY

REGEX

SUBSTRING

CISUBSTRING

=/!=/</<=/>/>=

  • 支持左值是集合:body体中左值为string。
  • 支持右值是集合:选择否,说明即使支持也仅匹配集合中第一个字符串。
  • boolean值匹配,当右值输入为”true”时,将被识别为“true”进行匹配,否则识别为“false”进行匹配。

响应参数

  • 同步返回
    表10 响应Body参数说明

    参数

    类型

    说明

    errorMessage

    String

    系统提示信息。

    • 执行成功时,字段可能为空。
    • 执行失败时,用于显示错误信息。

    errorCode

    String

    系统提示信息。

    • 执行成功时,字段可能为空。
    • 执行失败时,用于显示错误码。

    data

    Object

    查询结果。查询失败时,字段为空。

    表11 data参数说明

    参数

    类型

    说明

    vertices

    List

    点的结果集合。filters最后一层为点过滤时,data中将包含vertices。

    edges

    List

    边的结果集合。filters最后一层为边过滤时,data中将包含edges。

    paths

    List

    路径信息集合。with_path为true时可输出。格式见表12

    表12 path参数说明

    参数

    类型

    说明

    source

    String

    源点ID。

    target

    String

    终点ID。

    index

    String

    边index。

    label

    String

    边label。

  • 异步返回
    表13 响应Body参数说明

    参数

    类型

    说明

    errorMessage

    String

    系统提示信息。

    • 执行成功时,字段可能为空。
    • 执行失败时,用于显示错误信息。

    errorCode

    String

    系统提示信息。

    • 执行成功时,字段可能为空。
    • 执行失败时,用于显示错误码。

    jobId

    String

    执行算法任务ID。请求失败时,该字段为空。

    jobType

    Integer

    任务类型。请求失败时,该字段为空。

请求示例

  • (同步模式)列出满足过滤条件的第k跳节点或边,执行模式是同步,不进行可视化即查询job结果分页返回。
    POST /ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=filtered-query
    {
        "executionMode": "sync",
        "visulized": "false",
        "filters": [
            {
                "operator": "outV"
            },
            {
                "operator": "out",
                "edge_filter": {
                    "property_filter": {
                        "leftvalue": {
                            "label_name": "labelName"
                        },
                        "predicate": "=",
                        "rightvalue": {
                            "value": "rate"
                        }
                    }
                }
            }
        ],
        "full_path": false,
        "vertices": [
            "tr_10"
        ]
    }
  • (异步模式)列出满足过滤条件的第k跳节点或边,执行模式是异步,不进行可视化即查询job结果分页返回。
    POST /ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=filtered-query
    {
        "executionMode": "async",
        "visulized": "false",
        "filters": [
            {
                "operator": "outV"
            },
            {
                "operator": "out",
                "edge_filter": {
                    "property_filter": {
                        "leftvalue": {
                            "label_name": "labelName"
                        },
                        "predicate": "=",
                        "rightvalue": {
                            "value": "rate"
                        }
                    }
                }
            }
        ],
        "full_path": false,
        "vertices": [
            "tr_10"
        ]
    }
  • 嵌套property_filter,列出满足过滤条件的第k跳节点或边,执行模式是同步,不进行可视化即查询job结果分页返回。
    {
        "executionMode": "sync",
        "filters": [
            {
                "operator": "outV",
                 "vertex_filter": {
                    "property_filter": {
                        "leftvalue": {
                     "property_filter": {
                        "leftvalue": {
                            "property_name": "genres"
                         },
                      "predicate": "PREFIX",
                      "rightvalue": {
                      "value": "A|"
                }
              }
            },
                   "predicate": "&",
                   "rightvalue": {
                   "property_filter": {
                   "leftvalue": {
                   "label_name": "labelName"
                },
                   "predicate": "=",
                    "rightvalue": {
                     "value": "movie"
                  }
                }
              }
           }
         } 
        }
      ],
            "vertices": [
            "tr_3"
      ]
    }

响应示例

  • 同步返回

    状态码: 200

    成功响应示例

    Http Status Code: 200
    {
        "data": {
            "edges": [
                {
                    "index": "1",
                    "source": "tr_1",
                    "label": "rate",
                    "properties": {
                        "Rating": [
                            0
                        ],
                        "Datetime": [
                            ""
                        ]
                    },
                    "target": "tr_3"
                },
                ……,
                {
                    "index": "199998",
                    "source": "tr_1",
                    "label": "rate",
                    "properties": {
                        "Rating": [
                            0
                        ],
                        "Datetime": [
                            ""
                        ]
                    },
                    "target": "tr_200000"
                }
            ]
        }
    }
    

    状态码: 400

    失败响应示例
    Http Status Code: 400
    {
        "errorMessage": "graph [tesdt_117] is not found",
        "errorCode": "GES.8806"
    }
  • 异步返回

    状态码: 200

    成功响应示例

    Http Status Code: 200
    {
        "jobId": "6622f13c-4b88-45f5-89a9-eaa096647c4a",
        "jobType": 1
    }

    状态码: 400

    失败响应示例
    Http Status Code: 400
    {
        "errorMessage": "executionMode is not correct, it should be sync or async",
        "errorCode": "GES.8806"
    }

状态码

返回值

说明

400 Bad Request

请求错误。

401 Unauthorized

鉴权失败。

403 Forbidden

没有操作权限。

404 Not Found

找不到资源。

500 Internal Server Error

服务内部错误。

503 Service Unavailable

服务不可用。

错误码

请参见错误码