# Filtered-query V2(2.3.6) - FilteredQueryV2 #### 功能介绍 第二代filtered query。支持filtered query API和repeat query API共同的功能。 ![](https://support.huaweicloud.com/api-ges/public_sys-resources/note_3.0-zh-cn.png) 该接口支持对**多跳过滤查询** ，**循环执行遍历查询**进行加速。 例如以下gremlin语句： g.V('node1').repeat(out('label_2')).emit() #### URI POST /ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=path-query 表1路径参数 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释：** 项目编号。获取方法，请参见[获取项目ID](https://support.huaweicloud.com/api-ges/ges_03_0111.html)。 **约束限制：** 不涉及。 **取值范围：** 只能由英文字母和数字组成，且长度为\[1-64\]个字符。 **默认取值：** 不涉及。 | | graph_name | 是 | String | **参数解释：** 图名称。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 请求参数 ![](https://support.huaweicloud.com/api-ges/public_sys-resources/note_3.0-zh-cn.png) 每层traversal的元素个数不超过1亿。 表2Body参数说明 | 参数 | 是否必选 | 类型 | 默认值 | 说明 | |:---|:---|:---|:---|:---| | executionMode（2.2.22） | 否 | String | sync | **参数解释：** 执行模式。 **约束限制：** 不涉及。 **取值范围：** - sync：同步。 - async：异步。 **默认取值：** 默认为"async"，异步返回。 | | vertices | 是 | Array of Json | 无 | **参数解释：** 查询的起始节点ID列表。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | repeat | 是 | Array of Json | 无 | **参数解释：** 执行repeat的过滤条件列表，数组的每个元素分别对应每一层要做的查询和过滤条件。具体格式见[表repeat元素格式]。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | until（2.2.22） | 否 | Array of Json | 无 | **参数解释：** while/do looping模式。用于终止遍历过滤条件列表，具体格式见[until元素格式]。2.2.22版本until仅支持一个终止条件。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | times | 否 | Integer | 2 | **参数解释：** 用于限制最长步数。 **约束限制：** 最大值为20。 **取值范围：** 不涉及。 **默认取值：** 默认值为2。 | | emit | 否 | Boolean | false | **参数解释：** 是否返回所有元素。在输出select-as或tree下，emit的值决定了是否输出不在最终完整路径上的点。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 默认为false。 是否返回所有元素。默认为false。在输出select-as或tree下，emit的值决定了是否输出不在最终完整路径上的点。 | | limit | 否 | Integer | 10000 | **参数解释：** 控制点/边/path输出个数。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | queryType(2.2.22) | 否 | String | Default | **参数解释：** 查询模式。 **约束限制：** 不涉及。 **取值范围：** "Default"或"Tree"。 - Default为默认模式，即用户路径的查询内容。 - Tree返回用户路径查询的路径信息，并以tree的形式组织。 **默认取值：** 不涉及。 | | select(2.2.21) | 否 | Array of String | 无 | **参数解释：** 用来控制输出字段，可选择[as]中定义的字段。可以在参数 by中定义输出内容。 select有times+1个隐含的选择字段，v0,v1,v2...vtimes。其分别表示： - v0：用户输入的点集第0层。 - v1：K跳中的第1层。 - v2：K跳中的第2层等。 select选择的结果路径是默认去重的。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | by(2.2.21) | 否 | Array of Json | 输出所有 | **参数解释：** 用于控制输出字段具体内容。 **约束限制：** 1. 当字段不存在时，默认为输出所有内容。 2. 当选择select模式时，by的个数需与select的个数一致，且在select模式下，每个by只能输出一个元素。 3. 当没有使用select选择输出元素时，by作用在最终的结果集上，详情查看[by元素参数格式]。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | statistics | 否 | Boolean | false | **参数解释：** 是否仅返回命中个数。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** false。 | | mode | 否 | Boolean | 无 | **参数解释：** 强制指定traversal模式。默认策略会根据图结构自动切换。 **约束限制：** 不涉及。 **取值范围：** "Dense"或"Sparse"。 **默认取值：** 不涉及。 | | strategy | 否 | String | ShortestPath | **参数解释：** traversal策略。 **约束限制：** 不涉及。 **取值范围：** "ShortestPath"或"Walk"。 **默认取值：** 不涉及。 | | restricted(2.2.28) | 否 | Boolean | true | **参数解释：** 是否对输入严格校验。 **约束限制：** 不涉及。 **取值范围：** - 在true模式下，如果参数vertices中包含不存在的点，查询会直接退出并报错。 - 在false模式下，系统会把vertices中不存在的点过滤掉再进行查询任务。 **默认取值：** "true"。 | 表3by元素参数格式 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | id | 否 | Boolean | **参数解释：** 是否输出id。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** false。 | | label | 否 | Boolean | **参数解释：** 是否输出label。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** false。 | | properties | 否 | Boolean | **参数解释：** 是否输出properties。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** false。 | | selectedProperties | 否 | Array of String | **参数解释：** 当properties字段为true时，可以选择输出的属性项。字段为空时输出所有属性字段。该字段默认为空。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表4repeat元素格式 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | operator | 是 | String | **参数解释：** 表示要做的查询类型。 **约束限制：** 不涉及。 **取值范围：** 可选的值有：inV(入点), outV(出点), bothV(入点和出点)。 **默认取值：** 不涉及。 | | vertex_filter | 否 | JSON String | **参数解释：** 作用在下一跳的点上。具体格式见[property_filter元素格式]。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | edge_filter | 否 | JSON String | **参数解释：** 作用在点到点之间的边。具体格式见[property_filter元素格式]。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | as | 否 | JSON String | **参数解释：** 为该层元素取别名。后续可以用于定义输出字段。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表5until元素格式 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | vertex_filter | 否 | JSON String | **参数解释：** 在repeat 的operator为" inV"或"outV"或"bothV"时可选，具体格式见[property_filter元素格式]。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表6property_filter元素格式 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | leftvalue | 是 | String | **参数解释：** 左值，具体格式见[leftvalue元素格式]。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | predicate | 是 | String | **参数解释：** 表示过滤类型。支持的操作如下： 比较运算符： - =：等于 - !=：不等于 - \<：小于 - \<=：小于等于 - \>：大于 - \>=：大于等于 逻辑运算： - \&：与 - \|：或 集合运算： - IN/NOTIN：左值与右值是否有交集 - CONTAIN/NOTCONTAIN：属性值中是否含有右值 - SUBSET：右值是属性值的子集 匹配运算符： - PREFIX：右值是左值的前缀 - NOTPREFIX：右值不是左值的前缀 - SUFFIX：右值是左值的后缀 - NOTSUFFIX：右值不是左值的后缀 - SUBSTRING：右值是左值的子字符串 - NOTSUBSTRING：右值不是左值的子字符串 - FUZZY：模糊匹配 - REGEX：正则匹配 - CISUBSTRING：忽略大小写的子字符串 HAS/HASNOT：是否有此属性，仅支持属性过滤，即左值仅支持property_name。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | rightvalue | 是 | String | **参数解释：** 右值，具体格式见[rightvalue元素格式]。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表7leftvalue元素格式 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | label_name | 否 | String | **参数解释：** 若过滤"label"，可选"label_name"，值为"labelName"。rightvalue的value字段填具体的label的名称。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | property_name | 否 | String | **参数解释：** 若过滤"property"，可选"property_name"，值为属性名称，rightvalue的value字段填属性的值。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | id | 否 | String | **参数解释：** 若对节点ID做过滤，可选id，值可不填。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | property_filter | 否 | JSON String | **参数解释：** 若"predicate"为"\&"或者"\|"，可在"leftvalue"和"rightvalue"中嵌套使用"property_filter"。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | degree | 否 | String | **参数解释：** 代表点度数值过滤统计的方向。 **约束限制：** 不涉及。 **取值范围：** 可选\["both","in","out"\]。 **默认取值：** 不涉及。 | 表8rightvalue元素格式 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | value | 是 | String | **参数解释：** 若过滤"label"，值为label的名称。若过滤"property"，值为属性名称。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | property_filter | 否 | JSON String | **参数解释：** 若"predicate"为"\&"或者"\|"，可在"leftvalue"和"rightvalue"中嵌套使用"property_filter"。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表9predicate使用场景 | predicate | label_name | id | property_name | 嵌套filter | |:---|:---|:---|:---|:---| | \& | 否 | 否 | 否 | 是 | | \| | 否 | 否 | 否 | 是 | | HAS/HASNOT | 否 | 否 | 是 | 否 | | =/!=/\/\>= | 是 | 是 | 是 | 否 | #### 响应参数 - 同步返回 表10响应Body参数说明 | 参数 | 类型 | 说明 | |:---|:---|:---| | errorMessage | String | **参数解释**： 系统提示信息。 - 执行成功时，字段可能为空。 - 执行失败时，用于显示错误信息。 **取值范围**： 不涉及。 | | errorCode | String | **参数解释**： 系统提示信息。 - 执行成功时，字段可能为空。 - 执行失败时，用于显示错误码。 **取值范围**： 不涉及。 | | data | Object | **参数解释**： 查询结果。查询失败时，字段为空。 **取值范围**： 不涉及。 | 表11data参数说明 | 参数 | 类型 | 说明 | |:---|:---|:---| | vertices | List | **参数解释**： 点的结果集合。filters最后一层为点过滤时，data中将包含vertices。 **取值范围**： 不涉及。 | | edges | List | **参数解释**： 边的结果集合。filters最后一层为边过滤时，data中将包含edges。 **取值范围**： 不涉及。 | - 异步返回 表12响应Body参数说明 | 参数 | 类型 | 说明 | |:---|:---|:---| | errorMessage | String | **参数解释**： 系统提示信息。 - 执行成功时，字段可能为空。 - 执行失败时，用于显示错误信息。 **取值范围**： 不涉及。 | | errorCode | String | **参数解释**： 系统提示信息。 - 执行成功时，字段可能为空。 - 执行失败时，用于显示错误码。 **取值范围**： 不涉及。 | | jobId | String | **参数解释**： 执行算法任务ID。请求失败时，该字段为空。 说明： 可以查询jobId查看任务执行状态、获取返回结果，详情参考[Job管理API](https://support.huaweicloud.com/api-ges/ges_03_0036.html)。 **取值范围**： 不涉及。 | | jobType | Integer | **参数解释**： 任务类型。请求失败时，该字段为空。 **取值范围**： 不涉及。 | #### 请求示例 - 请求样例1：列出满足过滤条件的第k跳节点或边，查询类型是出点，作用在下一跳的点上。 ``` POST http://{SERVER_URL}/ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=path-query { "repeat":[ { "operator":"outV", "vertex_filter":{ "property_filter":{ "leftvalue":{ "label_name":"labelName" }, "predicate":"=", "rightvalue":{ "value":"rate" } } } } ], "times":2, "vertices":[ "1","2" ] } ``` ![](https://support.huaweicloud.com/api-ges/public_sys-resources/note_3.0-zh-cn.png) 以上请求等价于gremlin语句：g.V('1','2').repeat(out().hasLabel('rate')).times(2).dedup() - 请求样例2：列出满足过滤条件的第k跳节点或边，查询类型是出点，作用在下一跳的点上。 ``` POST http://{SERVER_URL}/ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=path-query { "repeat":[ { "operator":"outV", "vertex_filter":{ "property_filter":{ "leftvalue":{ "label_name":"labelName" }, "predicate":"=", "rightvalue":{ "value":"rate" } } } } ], "until":[ { "vertex_filter":{ "property_filter":{ "leftvalue":{ "property_name":"movieid" }, "predicate":"=", "rightvalue":{ "value":"1" } } } } ], "vertices":[ "v1","v2" ] } ``` ![](https://support.huaweicloud.com/api-ges/public_sys-resources/note_3.0-zh-cn.png) 以上请求等价于gremlin语句： g.V('v1','v2').repeat(out().hasLabel('rate')).until(has('movieid','1')).dedup() #### 响应示例 - 同步返回 **状态码： 200** 成功响应示例 ``` { "data":{ "vertices":[ { "id":"51", "label":"user", "properties":{ "occupation":[ "homemaker" ], "gender":[ "F" ], "Zip-code":[ "46911" ], "userid":[ 5 ], "age":[ "56+" ] } } ] } } ``` **状态码： 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 | 服务不可用。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-ges/ges_03_0110.html)。