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

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

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

Response Parameters

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

Error Codes

See Error Codes.