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

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.

NOTE:
  1. The slotted executor is supported since version 2.3.14.
  2. 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.

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.

  • 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:
    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.

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.

Error Codes

See Error Codes.