Executing Cypher Queries
Function
Cypher is a widely used declarative graph database query language. It can be used to query data in GES and returns results. Graph statistics are used in Cypher implementation. Currently, the label-based vertex and edge indexes are used during Cypher query and compilation. To use Cypher normally, create indexes by referring to Cypher Prerequisites.
URI
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 |
Example Request
Execute a Cypher query. The Cypher statement is match (n) return n limit 1. The returned results are in the format that each element corresponds to a field in the row.
POST http://{SERVER_URL}/ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=execute-cypher-query { "statements": [{ "statement": "match (n) return n limit 1", "parameters": {}, "resultDataContents": ["row"], "includeStats": false }] }
Request Parameters
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
statements |
Yes |
List |
Statement group that contains one or more statements. The statements parameters table describes the format of each element. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
statement |
Yes |
String |
Cypher statement |
parameters |
Yes |
Object |
Cypher statement parameters, which are used for parameterized queries. By default, this field is left blank. For details, see parameterized queries. |
resultDataContents |
No |
String or List |
Format of the returned result. You can set one or more formats. Available values are row, graph, and raw (added in version 2.2.27). |
includeStats |
No |
Boolean |
Whether the returned result contains addition, deletion, and modification statistics. If this parameter is not set, the returned result does not contain the information by default. |
runtime |
No |
String |
Executor type. The value can be map or slotted. The default value is map.
NOTE:
|
executionMode (2.2.23) |
No |
String |
Execution mode. Set this parameter to sync for synchronous execution and to async for asynchronous execution. If this parameter is not set, the execution is synchronous by default. For details about how to obtain the query result in asynchronous mode, see Querying Job Status on the Service Plane. |
limit (2.2.23) |
No |
Int |
Maximum number of results of the asynchronous query. This parameter is valid only when executionMode is sync. The default value is 100000. |
![](https://support.huaweicloud.com/eu/api-ges/public_sys-resources/note_3.0-en-us.png)
- You can add the explain and profile prefixes before the statement to display the query plan.
- explain displays only the query plan but does not execute the statement. The explain prefix is supported since version 2.2.20.
- profile displays the query plan and executes the statement. The profile prefix is supported since version 2.3.12.
- In asynchronous mode (executionMode is async), Cypher query results can be exported to CSV files (GES 2.3.4 or later supports this function). For details, see Exporting Job Execution Results to Files. Currently, the following values can be returned:
- Vertex and edge single-value properties, vertex and edge IDs, and group counts.
- The current version does not support exporting object types. Objects are converted to null values in the CSV file.
Response Parameters
Parameter |
Type |
Description |
---|---|---|
results |
List |
Each element of the list is the return result of a Cypher statement. |
errors |
List |
Each element in the list contains the code and message information in string form. |
Parameter |
Type |
Description |
---|---|---|
columns |
List |
Name of a returned field |
data |
List |
Returned data value. Each element indicates a record. |
stats |
Object |
Addition, deletion, and modification statistics |
plan |
Object |
If the Cypher statement contains the explain or profile prefix, this field contains the query plan. Otherwise, this field is not displayed. The profile feature is supported since version 2.3.12. |
jobId(2.3.10) |
String |
Asynchronous job ID if the request is executed asynchronously |
jobType(2.3.10) |
Integer |
Type of the asynchronous job if the request is executed asynchronously |
Parameter |
Type |
Description |
---|---|---|
row |
List |
Content of a specific row. Each element corresponds to a field in the row. This parameter is displayed only when resultDataContents is empty or contains row. |
meta |
List |
Type of each field in a row. This parameter is displayed only when resultDataContents is empty or contains row. |
graph |
Object |
Information returned in graph format. This parameter is displayed only when resultDataContents contains graph. |
raw(2.2.27) |
List |
Information returned in raw format. This parameter is displayed only when resultDataContents contains raw. |
Parameter |
Type |
Description |
---|---|---|
contains_updates |
Boolean |
Whether data is modified during the query |
edges_created |
Integer |
Number of created edges |
edges_deleted |
Int |
Number of deleted edges |
labels_set |
Integer |
Number of labels that have been set |
properties_set |
Integer |
Number of properties that have been set |
vertices_created |
Integer |
Number of created vertices |
vertices_deleted |
Integer |
Number of deleted vertices |
Example Response
Status code: 200
Example response for a successful request (synchronous call)
Http Status Code: 200 { "results": [ { "columns": ["n"], "data": [ { "row": [ { "occupation": "artist", "gender": "F", "Zip-code": "98133", "userid": 0, "age": "25-34" } ], "meta": [ { "id": "46", "type": "node", "labels": [ "user" ] } ] } ], "stats": { "contains_updates": false, "edges_created": 0, "edges_deleted": 0, "labels_set": 0, "properties_set": 0, "vertices_created": 0, "vertices_deleted": 0 } } ], "errors": [] }
Status code: 200
Example response for a successful request (asynchronous call)
Http Status Code: 200 { "results": [ { "columns": [ "jobId", "jobType" ], "jobId": "b64a5846-e306-4f87-b0f1-d595ee2a9910", "jobType": 1, "data": [ { "row": [ "b64a5846-e306-4f87-b0f1-d595ee2a9910", 1 ], "meta": [ null, null ] } ] } ], "errors": [] }
Status code: 400
Example response for a failed request
Http Status Code: 400 { "results": [], "errors": [ { "code": "GES.8904", "message": "Label index in vertices is not found." } ] }
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.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.