Updated on 2024-01-04 GMT+08:00

Filtered Query V2

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.

  1. If this parameter is not specified, all content is output by default.
  2. 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.
  3. 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 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.

  • Asynchronous response
    Table 12 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.

    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.

Error Codes

See Error Codes.