Filtered-query API(2.2.13) - FilteredQuery

功能介绍

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

URI

POST /ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=filtered-query

表1 路径参数
参数	是否必选	类型	说明
project_id	是	String	参数解释：项目编号。获取方法，请参见获取项目ID。约束限制：不涉及。取值范围：只能由英文字母和数字组成，且长度为[1-64]个字符。默认取值：不涉及。
graph_name	是	String	参数解释：图名称。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

请求参数

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

表2 Body参数说明
参数	是否必选	类型	说明
executionMode	否	String	参数解释：执行模式。约束限制：不涉及。取值范围： sync：同步。 async：异步。默认取值：默认为“async”，异步返回。
vertices	是	Array of Json	参数解释：查询的起始节点ID列表。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
query_type	否	String	参数解释：用户查询第k跳内容类型。约束限制：不涉及。取值范围： Default：为默认模式，即返回用户查询第k跳内容。 AllVertices：返回用户路径查询k跳以内所有点详情。 SimpleEdges：返回用户路径查询k跳以内所有边，仅包含边的id、index和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	参数解释：返回的路径信息是否是完整路径。约束限制：不涉及。取值范围：为“true”时，返回从起始节点到所有叶子节点的路径。为“false”时，返回从起始节点到第k层叶子节点的路径。默认取值： “false”。
visualized	否	Boolean	参数解释：是否可视化。约束限制：不涉及。取值范围：在异步模式下： “visualized”为“false”时，查询job结果分页返回。 “visualized”为“true”时，查询job结果不分页。默认取值： “false”。
restricted(2.2.28)	否	Boolean	参数解释：是否对输入严格校验。约束限制：不涉及。取值范围：在true模式下，如果参数vertices中包含不存在的点，查询会直接退出并报错。在false模式下，系统会把vertices中不存在的点过滤掉再进行查询任务。默认取值： “true”。

表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	参数解释：路径信息集合。格式为[[path1],[path2]]，path的格式见表12。取值范围：不涉及。

**表12** path参数说明
参数	类型	说明
source	String	参数解释：源点ID。取值范围：不涉及。
target	String	参数解释：终点ID。取值范围：不涉及。
index	String	参数解释：边index。取值范围：不涉及。
label	String	参数解释：边label。取值范围：不涉及。

异步返回

**表13** 响应Body参数说明
参数	类型	说明
errorMessage	String	参数解释：系统提示信息。执行成功时，字段可能为空。执行失败时，用于显示错误信息。取值范围：不涉及。
errorCode	String	参数解释：系统提示信息。执行成功时，字段可能为空。执行失败时，用于显示错误码。取值范围：不涉及。
jobId	String	参数解释：执行算法任务ID。请求失败时，该字段为空。说明：可以查询jobId查看任务执行状态、获取返回结果，详情参考Job管理API。取值范围：不涉及。
jobType	Integer	参数解释：任务类型。请求失败时，该字段为空。取值范围：不涉及。

请求示例

（同步模式）列出满足过滤条件的第k跳节点或边，执行模式是同步，不进行可视化即查询job结果分页返回。

POST http://{SERVER_URL}/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 http://{SERVER_URL}/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结果分页返回。

POST http://{SERVER_URL}/ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=filtered-query
{
    "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": "Not found. Please check the input parameters.",
    "errorCode": "GES.8000"
}

状态码

返回值	说明
400 Bad Request	请求错误。
401 Unauthorized	鉴权失败。
403 Forbidden	没有操作权限。
404 Not Found	找不到资源。
500 Internal Server Error	服务内部错误。
503 Service Unavailable	服务不可用。