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

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

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

**Table 2** Request body parameter
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.

**Table 3** statements parameters
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. The slotted executor is supported since version 2.3.15.
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.
transactional	No	Bool	Whether the Cypher request is transactional. The default value is false. For details about Cypher transactions, see Cypher transactions.

You can add the explain or profile prefix before a statement to display the query plan. The explain prefix displays only the query plan but does not execute the statement. The profile prefix displays the query plan and executes the statement.
Description of the runtime field: Compared with the map executor, the slotted executor completes more statement data flow analysis in the plan generation phase of statements. In most cases, it executes faster while requiring less memory.
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:
1. Vertex and edge single-value properties, vertex and edge IDs, and group counts.
2. The current version does not support exporting object types. Objects are converted to null values in the CSV file.
Cypher transactions (database edition only):
1. For database edition graphs, Cypher transactions are supported. You can set transactional to true to enable the function to ensure the atomicity of a single Cypher statement. Transactions supporting multiple Cypher statements are not available. Transactions in GES use a serializability isolation level.
2. The transaction time window is limited to 5s in the underlying storage engine of GES. Cypher transactions cannot last exceeding 5s. For complex queries, such as multi-hop queries, the running time may exceed 5s. The transaction times out and the submission fails.
  In this case, you can use the dbms.killQuery program of Cypher to terminate a Cypher transaction (for details, see Cypher API-Functions and Procedures) and restore all changes caused by the Cypher request.

Response Parameters

**Table 4** Response body 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.

**Table 5** Elements of the results parameter
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

**Table 6** Elements of the data parameter
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.

**Table 7** **stats** elements in a response
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.