Executing Transaction Cypher Statements

Function

This API is used to execute transaction Cypher statements.

URI

POST /ges/v1.0/{project_id}/graphs/{graph_name}/transaction/{commit}

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For how to obtain the project ID, see Obtaining a Project ID.
graph_name	Yes	String	Graph name
commit	Yes	String	Transaction ID, which is obtained by calling the transaction creation API.

Request Parameters

**Table 2** Request body parameter
Parameter	Mandatory	Type	Description
statements	Yes	List	Statement group that contains one or more statements. Table 3 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. This parameter is left blank by default. For details, see parameterized queries.
resultDataContents	No	String or List	Format of the execution results. You can set one or more formats. The options are row, graph, and raw (new 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, slotted, or block. The default value is map. The slotted executor is supported since version 2.3.15, and the block executor is supported since version 2.4.1.
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 how to obtain the query results in asynchronous mode, refer to Querying Job Status on the Service Plane (1.0.0).
limit (2.2.23)	No	Int	Maximum number of asynchronous results. This parameter applies only when executionMode is sync. The default value is 100000.

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 (2.2.1). 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 ensure the atomicity of a single Cypher statement. Transactions supporting multiple Cypher statements are not supported. Transactions in GES use a serializability isolation level.
2. Since the underlying storage engine has a transaction time window limit of 5 seconds, the transactions for Cypher statements cannot exceed 5 seconds. For complex queries, such as those with multiple hops, the execution time may exceed 5 seconds, resulting in timeouts and failed submissions.
  In this case, you can use the dbms.killQuery program of Cypher to terminate a Cypher transaction (see Supported Expressions, Functions, and Procedures) and roll back all changes caused by this 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 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}/transaction/{commit}
{
       "statements": [{
              "statement": "match (n) return n limit 1",
              "parameters": {},
              "resultDataContents": ["row"],
              "includeStats": false
       }]
}

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

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.