Querying Vertices That Meet Filter Criteria (1.0.0)

Function

This API is used to query vertices that meet filter criteria.

URI

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

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
labels	Either labels or vertexFilters is mandatory.	String	Filter criteria of the vertex type
vertexFilters	Either labels or vertexFilters is mandatory.	Object	Filter criteria, in JSONArray format. Vertices are filtered by property.
offset	No	Integer	Start position of the request
limit	No	Integer	Maximum number of resources displayed on a single page. The default value is 10.
sorts	No	Object	Result sorting property, in JSONArray format

**Table 3** sorts parameter description
Parameter	Mandatory	Type	Description
key	Either Key or propertyName is mandatory.	String	Possible values are id, label, and property. These values indicate that IDs, labels, or properties are sorted.
propertyName	Either Key or propertyName is mandatory.	String	Property name
orderValue	No	String	Possible values are incr and decr, which indicate ascending and descending order respectively. The default value is incr.

**Table 4** **vertexFilters** parameter structure
Parameter	Mandatory	Type	Description
propertyName	Yes	String	Property name
predicate	Yes	String	Predicate. Available values are =, <, >, <=, >=, range, has, hasNot, full_text_match, full_text_prefix, full_text_wildcard, full_text_regexp, full_text_fuzzy, and full_text_combination. NOTE: If the property is of the composite type, such as list or set, the predicate can only be has or hasNot.
values	No	String	Property value. If predicate is full_text_combination, values cannot be a string. For details, see Example 2 for vertexFilters (full_text_combination).
type	No	String	Logical operator of the filter criteria. Possible values are and and or. The default value is and.

Response Parameters

**Table 5** 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 vertex query job. This parameter is left blank when the request fails. NOTE: You can view the job execution status and obtain the return result by querying the job ID. For details, see Querying Job Status on the Service Plane (1.0.0).
jobType	Integer	Job type. This parameter is left blank when the request fails.

Example Request

Query vertices that meet filter criteria. The start position of the request is 0, the maximum number of resources on each page is 2, the attribute criteria for filtering are movie and user, and the attribute name for filtering is Age.

POST https://{SERVER_URL}/ges/v1.0/{project_id}/graphs/{graph_name}/vertices/action?action_id=query  

{
   "offset":0,
   "limit":2,
   "labels": ["movies",
             "user"],
   "vertexFilters":[{
      "propertyName":"Age",
      "predicate":"=", 
      "values":["18-24"]
      }
   ]
}

SERVER_URL: Address for accessing a graph. For details about its value, see Using Service Plane APIs.

Example 1 for vertexFilters

[
 {
   "propertyName":"Gender",
   "predicate":"=",
   "values":["F"]
 },
 {
   "propertyName":"Age",
   "predicate":"range", 
   "values":["18-24","56+"],
   "type":"or"
 }
]

Example 2 for vertexFilters, with predicate set to full_text_combination

"vertexFilters": [
        {
            "propertyName": "propertyName",
            "predicate": "full_text_combination",
            "values": [
                {
                    "propertyName": "movieid",
                    "value": "0"
                },
                {
                    "propertyName": "title",
                    "value": "american"
                }
            ]
        }
    ]

When predicate is set to full_text_match, full_text_prefix, full_text_wildcard, full_text_regexp, full_text_fuzzy, or full_text_combination, the vertexFilters list can contain only one element, that is, multi-layer filters are not allowed. The labels parameter cannot be used at the same time. When predicate is full_text_combination, set the outermost propertyName to propertyName. In this case, the values parameter is not a simple string list. Each element of the values list has two members: propertyName and value. To use the full-text index, you need to call the API for creating a full-text index first.

Example Response

Status code: 200

Example response for a successful request

Http Status Code: 200
{
    "jobId": "03e774f5-29ea-4187-9508-5435f3892ead016886200",
    "jobType": 1
}

Status code: 400

Example response for a failed request

Http Status Code: 400
{
    "errorMessage": "Bad Request, parameter labels and vertexFilters cannot all be null",
    "errorCode": "GES.8203"
}

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.