Filtered Query V2 (2.3.6)

Function

This is a new version of the Filtered Query API. This API supports both Filtered Query and Repeat Query functions.

You can use this API to accelerate multi-hop filtered query and looped traversal query.

For example, a Gremlin statement is as follows:

g.V('node1').repeat(out('label_2')).emit()

URI

POST /ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=path-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.

Request Parameters

The number of elements in each traversal cannot exceed 100 million.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Default Value	Description
executionMode (2.2.22)	No	String	sync	Execution mode of the query task. The value can be sync (synchronously) or async (asynchronously).
vertices	Yes	Array of Json	None	List of IDs of source vertices you want to query
repeat	Yes	Array of Json	None	Filter criteria for repeat queries. Each element in the array corresponds to a filter. For details about the format, see Table 4.
until (2.2.22)	No	Array of Json	None	Conditions to stop the traversal. The logic is similar to while/do loop. For details about the format, see until elements. For APIs of the 2.2.22 version, until supports only one stop condition.
times	No	int	2	Maximum number of steps. The default value is 2, and the maximum value is 20.
emit	No	Boolean	false	Whether all elements will be returned. The default value is false. If select and as are configured, or queryType is set to Tree, this parameter determines whether vertices that are not on the final complete path will be returned.
limit	No	int	10000	Number of vertices, edges, or paths.
queryType(2.2.22)	No	String	Default	Type of the query. The value can be Default or Tree. Default means that the path query result will be returned. Tree means that the path information of the path query will be returned in the tree structure.
select (2.2.21)	No	Array of String	None	Fields you want to be displayed in the result. The values can be the fields set in the as parameter, or you can set the by parameter together with this parameter to control output content. If you set the by parameters together, you can set select to v0, v1, v2, ..., and vtimes: v0: layer 0 of the K hops v1: the first layer of the K hops v2: the second layer of the K hops The path selected by this parameter is deduplicated by default.
by(2.2.21)	No	Array of Json	Output all	Content of output fields. If this parameter is not specified, all content is output by default. If the select parameter is configured, the number of by must be the same as the number of select. Each by can output only one element. If select is not configured, by takes effect on the final result set. For details, see by elements.
statistics	No	Boolean	false	Whether only the number of hit records will be returned. The default value is false.
mode	No	Boolean	None	Traversal mode that will be set forcibly. The value can be Dense or Sparse. The default mode is automatically switched based on the graph structure.
strategy	No	String	ShortestPath	Traversal policy. The value can be ShortestPath or Walk.
restricted(2.2.28)	No	Boolean	true	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** by elements
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.

**Table 4** repeat elements
Parameter	Mandatory	Type	Description
operator	Yes	String	Type of the query. The value can be inV (incoming vertex), outV (outgoing vertex), and bothV (incoming and outgoing vertices).
vertex_filter	No	JSON String	Search conditions for the next hop. For details about the format, see property_filter elements.
edge_filter	No	JSON String	Edge search conditions. For details about the format, see property_filter elements.
as	No	JSON String	Alias of elements at this layer. The value can be used to select output fields.

**Table 5** until elements
Parameter	Mandatory	Type	Description
vertex_filter	No	JSON String	This parameter is optional when operator in repeat is set to inV, outV, or bothV. For details about the format, see property_filter elements.

**Table 6** property_filter elements
Parameter	Mandatory	Type	Description
leftvalue	Yes	String	Left value of a search condition. For details, see leftvalue elements.
predicate	Yes	String	Filtering type. The options are as follows: 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 format, see rightvalue elements.

**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	JSON String	If predicate is set to & or \|, property_filter can be nested in leftvalue and rightvalue.
degree	No	String	Direction of vertex degree filtering statistics. This parameter is optional. The value can be both, in, or out.

**Table 8** rightvalue elements
Parameter	Mandatory	Type	Description
value	Yes	String	If label is used as the search criterion, the value is the label name. If property is used as the search criterion, the value is the property name.
property_filter	No	JSON 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
=/!=/</<=/>/>=	Yes	Yes	Yes	No

Response Parameters

Synchronous response

**Table 10** Response body parameters
Parameter	Type	Description
errorMessage	String	System prompt. If the execution succeeds, this parameter may be left blank. If the execution fails, this parameter is used to display the error message.
errorCode	String	System prompt. If the execution succeeds, this parameter may be left blank. If the 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.

Asynchronous response

**Table 12** Response body parameters
Parameter	Type	Description
errorMessage	String	System prompt. If the execution succeeds, this parameter may be left blank. If the execution fails, this parameter is used to display the error message.
errorCode	String	System prompt. If the execution succeeds, this parameter may be left blank. If the execution fails, this parameter is used to display the error code.
job_id	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

Example request 1: List the kth-hop vertices or edges that meet filter criteria. The query type is outgoing vertex, and the query is performed on the next-hop vertex.

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

The preceding request is equivalent to this Gremlin statement: g.V('1','2').repeat(out().hasLabel('rate').times(2).dedup().

Example request 2: List the kth-hop vertices or edges that meet filter criteria. The query type is outgoing vertex, and the query is performed on the next-hop vertex.

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

The preceding request is equivalent to this Gremlin statement:

g.V('v1','v2').repeat(out().hasLabel('rate')).until(has('movieid','1')).dedup()

Example Response

Synchronous response

Status code: 200

Example response for a successful request

{
     "data":{
         "vertices":[
             {
                 "id":"51",
                 "label":"user",
                 "properties":{
                     "occupation":[
                         "homemaker"
                     ],
                     "gender":[
                         "F"
                     ],
                     "Zip-code":[
                         "46911"
                     ],
                     "userid":[
                         5
                     ],
                     "age":[
                         "56+"
                     ]
                 }
             }
         ]
     }
 }

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.