Filtered Query

Function

This API filters the k-hop process layer by layer, and lists the k hop vertices or edges that meet the filtering criteria.

URI

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

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.
graph_name	Yes	String	Graph name

Request Parameters

If executionMode is sync, the number of returned vertices cannot exceed 100,000.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
executionMode	No	String	sync: synchronous async: asynchronous The default value is sync, indicating synchronous response.
vertices	Yes	Array of Json	List of IDs of source vertices you want to query
query_type	No	String	Possible values are Default, AllVertices, SimpleEdges, Path. Default indicates the default mode, that is, the k hop is returned. AllVertices returns details about all vertices within k hops. SimpleEdges returns all edges within k hops, contain only the ID and label information of the edges. Path returns the path information, that is, the set of paths.
by	No	Array of Json	Specified output field. This parameter is valid only when query_type is set to Default or AllVertices. Currently, only one layer is supported. If this parameter is not specified, all content is output by default.
edges	No	Array of Json	List of edges to be queried. Either this parameter or vertices is selected. For details, see Table 3.
filters	Yes	Array of Json	Filter criteria. Each element in the array corresponds to a filter. For details about the formats, see Table 4.
full_path	No	Boolean	Whether to return a complete path. The default value is false. If the value is true, the paths from the source vertex to all leaf vertices are returned. If the value is false, the paths from the source vertex to the leaf vertices at layer k are returned.
visualized	No	Boolean	Whether to enable visualization. The default value is false. In asynchronous mode: When visualized is false, the job query result is returned on multiple pages. When visualized is true, the job query result is returned on one page.
restricted(2.2.28)	No	Boolean	Whether the input is restricted. The default value is true. true: If vertices contains vertices that do not exist, the query exits and an error is reported. false: The system filters out vertices that do not exist and then performs the query task.

**Table 3** **edges** element formats
Parameter	Mandatory	Type	Description
source	Yes	String	Source vertex ID
target	Yes	String	Target vertex ID
index	No	String	Indexes of edges in the source edge set

**Table 4** **Filters** element formats
Parameter	Mandatory	Type	Description
operator	Yes	String	Query type. Possible values: inV: incoming vertex outV: outgoing vertex bothV: incoming and outgoing vertices vertex: all vertices. Filtering is available only at the first layer. If vertices are input in the beginning, the first-layer output is the input vertices. If no vertices are input in the beginning, all vertices are output at the first layer. in: incoming edge out: outgoing edge both: incoming and outgoing edges edge: all edges. Filtering is available only at the first layer. The usage is similar to that of vertices The query result of the previous layer is the input of the next layer. If the result of the previous layer is a vertex, the corresponding operations can be inV, outV, bothV, in, out, and both. If the result of the previous layer is an edge, the corresponding operation can be inV, outV, and bothV.
vertex_filter	No	String	This parameter is optional when operator is set to inV, outV, or bothV. For details about the formats, see Table 6.
edge_filter	No	String	This parameter is optional when operator is set to in, out, or both. For details about the formats, see Table 6.

**Table 5** by element formats
Parameter	Mandatory	Type	Description
id	No	Boolean	Whether to output the ID. The default value is false.
label	No	Boolean	Whether to output the label. The default value is false.
properties	No	Boolean	Whether to output properties. The default value is false.
selectedProperties	No	Array of String	When properties is set to true, you can select the properties to be output. If this parameter is left blank, all properties are output. By default, this parameter is left blank.

**Table 6** property_filter elements
Parameter	Mandatory	Type	Description
leftvalue	Yes	String	Left value. For details about the formats, see Table 7.
predicate	Yes	String	Filtering type. The supported operations include: Relational operators: =: equal to !=: not equal to <: less than ≤: Less than or equal to >: greater than ≥: greater than or equal to Logical operations: &: and \|: or Set operations: IN/NOTIN: whether the left value and right value have an intersection CONTAIN/NOTCONTAIN: whether the property value contains the right value. SUBSET: The right value is a subset of the property value. Match operators: PREFIX: The right value is the prefix of the left value. NOTPREFIX: The right value is not the prefix of the left value. SUFFIX: The right value is the suffix of the left value. NOTSUFFIX: The right value is not the suffix of the left value. SUBSTRING: The right value is a sub-string of the left value. NOTSUBSTRING: The right value is not a sub-string of the left value. FUZZY: fuzzy match REGEX: expression match CISUBSTRING: sub-string that ignores cases HAS/HASNOT: whether this property exists. Only property filtering is supported. That is, the left value can only be property_name.
rightvalue	Yes	String	Right value. For details about the formats, see Table 8.

**Table 7** leftvalue elements
Parameter	Mandatory	Type	Description
label_name	No	String	If label is used as the filter criterion, label_name can be selected and the value is labelName. Set the value field of rightvalue to the label name.
property_name	No	String	If property is used as the filter criterion, set this parameter to the property name and set value of rightvalue to the property value.
id	No	String	If the vertex ID is filtered, this parameter is optional.
property_filter	No	String	If predicate is set to & or \|, property_filter can be nested in leftvalue and rightvalue.

**Table 8** rightvalue elements
Parameter	Mandatory	Type	Description
value	Yes	String	If label is used as the filter criterion, the value is the label name. If property is used as the filter criterion, the value is the property name.
property_filter	No	String	If predicate is set to & or \|, property_filter can be nested in leftvalue and rightvalue.

**Table 9** predicate supported left values
predicate	label_name	id	property_name	Nested Filters
&	No	No	No	Yes
\|	No	No	No	Yes
HAS/HASNOT	No	No	Yes	No
CONTAIN/NOTCONTAIN	No	No	Yes	No
SUBSET	No	No	Yes	Yes (Only the right value set is supported. If the right value is single, no filtering function is available.)
IN/NOTIN	Yes	Yes	Yes	Yes (Only the right value set is supported. If the right value is single, no match is available.)
PREFIX	Yes	Yes	Yes	No
FUZZY	Yes	Yes	Yes	No
REGEX	Yes	Yes	Yes	No
SUBSTRING	Yes	Yes	Yes	No
CISUBSTRING	Yes	Yes	Yes	No
=/!=/</<=/>/>=	Yes	Yes	Yes	No

The left value set is supported. The left value in the body is a string.
The right value set is supported. If you select No, only the first character string in the set is matched even if the right value set is supported.
Boolean value matching. When the right value is true, the value is identified as true for matching. Otherwise, the value is identified as false for matching.

Response Parameters

Synchronous response

**Table 10** Response body parameters
Parameter	Type	Description
errorMessage	String	System prompt. If execution succeeds, this parameter may be left blank. If execution fails, this parameter is used to display the error message.
errorCode	String	System prompt code. If execution succeeds, this parameter may be left blank. If execution fails, this parameter is used to display the error code.
data	Object	Query results. This parameter is left blank when the query fails.

**Table 11** data parameter description
Parameter	Type	Description
vertices	List	Vertex result set. If the last layer of filters is vertex filtering, the data contains vertices.
edges	List	Edge result set. If the last layer of filters is edge filtering, the data contains edges.
paths	List	Path set. This parameter is available only when with_path is set to true. For details about the formats, see Table 12.

**Table 12** path parameter description
Parameter	Type	Description
source	String	Source vertex ID
target	String	Target vertex ID
index	String	Edge index
label	String	Edge label

Asynchronous response

**Table 13** Response body parameters
Parameter	Type	Description
errorMessage	String	System prompt. If execution succeeds, this parameter may be left blank. If execution fails, this parameter is used to display the error message.
errorCode	String	System prompt code. If execution succeeds, this parameter may be left blank. If execution fails, this parameter is used to display the error code.
jobId	String	ID of the algorithm execution job. This parameter is left blank when the request fails.
jobType	Integer	Job type. This parameter is left blank when the request fails.

Example Request

(Synchronous mode) List the kth-hop vertices or edges that meet filter criteria. The execution mode is synchronous. Visualization is not performed. That is, job query results are displayed on multiple pages.

POST /ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=filtered-query
{
    "executionMode": "sync",
    "visualized": "false",
    "filters": [
        {
            "operator": "outV"
        },
        {
            "operator": "out",
            "edge_filter": {
                "property_filter": {
                    "leftvalue": {
                        "label_name": "labelName"
                    },
                    "predicate": "=",
                    "rightvalue": {
                        "value": "rate"
                    }
                }
            }
        }
    ],
    "full_path": false,
    "vertices": [
        "tr_10"
    ]
}

(Asynchronous mode) List the kth-hop vertices or edges that meet filter criteria. The execution mode is asynchronous. Visualization is not performed. That is, job query results are displayed on multiple pages.

POST /ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=filtered-query
{
    "executionMode": "async",
    "visualized": "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 is nested. List the kth-hop vertices or edges that meet filter criteria. The execution mode is synchronous. Visualization is not performed. That is, job query results are displayed on multiple pages.

{
    "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"
  ]
}

Example Response

Synchronous response

Status code: 200

Example response for a successful request

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"
            }
        ]
    }
}

Status code: 400

Example response for a failed request

Http Status Code: 400
{
    "errorMessage": "graph [tesdt_117] is not found",
    "errorCode": "GES.8806"
}

Asynchronous response

Status code: 200

Example response for a successful request

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

Status code: 400

Example response for a failed request

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

Status Codes

Return Value	Description
400 Bad Request	Request error.
401 Unauthorized	Authorization failed.
403 Forbidden	No operation permissions.
404 Not Found	No resources found.
500 Internal Server Error	Internal server error.
503 Service Unavailable	Service unavailable.