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

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.

Error Codes

See Error Codes.