# 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](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) 当executionMode为同步时，返回的点个数不能超过10万。 表2Body参数说明 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | 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"。 | 表3edges元素格式 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | source | 是 | String | **参数解释：** 源节点ID。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | target | 是 | String | **参数解释：** 目标节点ID。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | index | 否 | String | **参数解释：** 此边在源节点边集合中的索引。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表4Filters元素格式 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | 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]。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表5by元素格式 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | id | 否 | Boolean | **参数解释：** 是否输出id。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** false。 | | label | 否 | Boolean | **参数解释：** 是否输出label。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** false。 | | properties | 否 | Boolean | **参数解释：** 是否输出properties。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** false。 | | selectedProperties | 否 | Array of String | **参数解释：** 输出的属性项。当properties字段为true时，可以选择输出的属性项。 字段为空时输出所有属性字段。默认为空。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表6property_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]。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表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 | 否 | String | **参数解释：** 若"predicate"为"\&"或者"\|"，可在"leftvalue"和"rightvalue"中嵌套使用"property_filter"。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表8rightvalue元素格式 | 参数 | 是否必选 | 类型 | 说明 | |:---|:---|:---|:---| | value | 是 | String | **参数解释：** - 若过滤"label"，值为label的名称。 - 若过滤"property"，值为属性名称。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | property_filter | 否 | String | **参数解释：** 若"predicate"为"\&"或者"\|"，可在"leftvalue"和"rightvalue"中嵌套使用"property_filter"。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表9predicate使用场景 | predicate | label_name | id | property_name | 嵌套filter | |:---|:---|:---|:---|:---| | \& | 否 | 否 | 否 | 是 | | \| | 否 | 否 | 否 | 是 | | HAS/HASNOT | 否 | 否 | 是 | 否 | | CONTAIN/NOTCONTAIN | 否 | 否 | 是 | 否 | | SUBSET | 否 | 否 | 是 | 是（仅支持右值为集合，若为single，则无过滤作用直接匹配） | | IN/NOTIN | 是 | 是 | 是 | 是（仅支持右值为集合，若为single，则不匹配） | | PREFIX | 是 | 是 | 是 | 否 | | FUZZY | 是 | 是 | 是 | 否 | | REGEX | 是 | 是 | 是 | 否 | | SUBSTRING | 是 | 是 | 是 | 否 | | CISUBSTRING | 是 | 是 | 是 | 否 | | =/!=/\/\>= | 是 | 是 | 是 | 否 | ![](https://support.huaweicloud.com/api-ges/public_sys-resources/note_3.0-zh-cn.png) - 支持左值是集合：body体中左值为string。 - 支持右值是集合：选择否，说明即使支持也仅匹配集合中第一个字符串。 - boolean值匹配，当右值输入为"true"时，将被识别为"true"进行匹配，否则识别为"false"进行匹配。 #### 响应参数 - 同步返回 表10响应Body参数说明 | 参数 | 类型 | 说明 | |:---|:---|:---| | errorMessage | String | **参数解释**： 系统提示信息。 - 执行成功时，字段可能为空。 - 执行失败时，用于显示错误信息。 **取值范围**： 不涉及。 | | errorCode | String | **参数解释**： 系统提示信息。 - 执行成功时，字段可能为空。 - 执行失败时，用于显示错误码。 **取值范围**： 不涉及。 | | data | Object | **参数解释**： 查询结果。查询失败时，字段为空。 **取值范围**： 不涉及。 | 表11data参数说明 | 参数 | 类型 | 说明 | |:---|:---|:---| | vertices | List | **参数解释**： 点的结果集合。filters最后一层为点过滤时，data中将包含vertices。 **取值范围**： 不涉及。 | | edges | List | **参数解释**： 边的结果集合。filters最后一层为边过滤时，data中将包含edges。 **取值范围**： 不涉及。 | | paths | List | **参数解释**： 路径信息集合。格式为\[\[path1\],\[path2\]\]，path的格式见[表12]。 **取值范围**： 不涉及。 | 表12path参数说明 | 参数 | 类型 | 说明 | |:---|:---|:---| | source | String | **参数解释**： 源点ID。 **取值范围**： 不涉及。 | | target | String | **参数解释**： 终点ID。 **取值范围**： 不涉及。 | | index | String | **参数解释**： 边index。 **取值范围**： 不涉及。 | | label | String | **参数解释**： 边label。 **取值范围**： 不涉及。 | - 异步返回 表13响应Body参数说明 | 参数 | 类型 | 说明 | |:---|:---|:---| | errorMessage | String | **参数解释**： 系统提示信息。 - 执行成功时，字段可能为空。 - 执行失败时，用于显示错误信息。 **取值范围**： 不涉及。 | | errorCode | String | **参数解释**： 系统提示信息。 - 执行成功时，字段可能为空。 - 执行失败时，用于显示错误码。 **取值范围**： 不涉及。 | | jobId | String | **参数解释**： 执行算法任务ID。请求失败时，该字段为空。 说明： 可以查询jobId查看任务执行状态、获取返回结果，详情参考[Job管理API](https://support.huaweicloud.com/api-ges/ges_03_0036.html)。 **取值范围**： 不涉及。 | | 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 | 服务不可用。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-ges/ges_03_0110.html)。