Cypher Operation API

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.

URL

• URI format

  POST /ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=execute-cypher-query

• Parameter description

  Table 1 URI parameter description

  Parameter	Mandatory	Type	Description
  project_id	Yes	String	Project ID, which is used for resource isolation.
  graph_name	Yes	String	Graph name

Request

• Request example

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
       }]
}

• Parameter description

  Table 2 Request body parameter description

  Parameter	Mandatory	Type	Description
  statements	Yes	List	Statement group that contains one or more statements. statements parameter description describes the format of each element.

  Table 3 statements parameter description

  Parameter	Mandatory	Type	Description
  statement	Yes	String	Cypher statement
  parameters	Yes	Json	Cypher statement parameters, which are used for parameterized query. By default, this parameter 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.
  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.

Response

• Parameter description

  Table 4 Parameter description

  Parameter	Mandatory	Type	Description
  results	Yes	List	A List. Each element is the return result of a Cypher statement.
  errors	Yes	List	A list. Each element in the list contains the code and message information in the form of character strings.

  Table 5 Elements of the results parameter

  Parameter	Mandatory	Type	Description
  columns	Yes	List	Name of a returned field
  data	Yes	List	Returned data value. Each element indicates a record.
  stats	No	Json	Addition, deletion, and modification statistics
  plan	No	Json	If the cypher statement contains the explain prefix, this field contains the query plan. Otherwise, this field is not displayed.

  Table 6 Elements of the data parameter

  Parameter	Mandatory	Type	Description
  row	No	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	No	List	Type of each field in a row. This parameter is displayed only when resultDataContents is empty or contains row.
  graph	No	Json	Returns the information in a row in graph format. This parameter is displayed only when resultDataContents contains graph.

• Response example (successful request)

  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": []
  }
  

  Table 7 Response parameters of stats elements

  Parameter	Mandatory	Type	Description
  contains_updates	Yes	Boolean	Whether data is modified during the query
  edges_created	Yes	Integer	Number of created edges
  edges_deleted	Yes	Int	Number of deleted edges
  labels_set	Yes	Integer	Number of labels that have been set
  properties_set	Yes	Integer	Number of properties that have been set
  vertices_created	Yes	Integer	Number of created vertices
  vertices_deleted	Yes	Integer	Number of deleted vertices

• Response example (failed request)

  Http Status Code: 400
  {
      "results": [],
      "errors": [
          {
              "code": "GES.8904",
              "message": "Label index in vertices is not found."
          }
      ]
  }

Response Code

• Normal

200

• Abnormal

  Table 8 Return code for failed requests

  Response Code	Description
  400 Bad Request	Request error.
  401 Unauthorized	Authentication failed.
  403 Forbidden	No operation permission.
  404 Not Found	The requested resource was not found.
  500 Internal Server Error	Internal service error.
  503 Service Unavailable	Service unavailable.

Cypher Prerequisites

The current Cypher query compilation process uses the label-based vertex and edge indexes. To use Cypher normally, use the index creation API to create indexes. The following is an example:

• Example for creating a vertex label index:

  POST http://{SERVER_URL}/ges/v1.0/{project_id}/graphs/{graph_name}/indices
  {
          "indexName": "cypher_vertex_index",
          "indexType": "GlobalCompositeVertexIndex",
          "hasLabel": "true",
          "indexProperty": []
  }

• Example for creating an edge label index:

  POST http://{SERVER_URL}/ges/v1.0/{project_id}/graphs/{graph_name}/indices
  {
          "indexName": "cypher_edge_index",
          "indexType": "GlobalCompositeEdgeIndex",
          "hasLabel": "true",
          "indexProperty": []
  }

  

  1. You must create two indexes (vertex label index and edge label index) at the same time to use Cypher for query.
  2. If a vertex index or an edge index whose hasLabel is true and indexProperty is empty exists in the graph, you do not need to create the vertex index or edge index again.
  3. The API for creating an index is an asynchronous API. To check whether the index is successfully created, use the API for querying the job status.

Basic Operations

Compatibility for Cypher Implementation

• Clauses supported by Cypher

  Cypher implements a couple of clauses. You can combine clauses to implement different query semantics, including vertex and edge filtering, multi-hop query, sorting and deduplication, and grouping and aggregation. Currently, GES supports the following Cypher clauses:

  Table 9 Clauses supported by Cypher

  Clause	Support	Example
  match	Partially supported	match (n:movie) return n
  return	Supported	return [1,2,3] as p
  with	Supported	match (n) with labels(n) as label, count(*) as count where count > 10 return *
  where	Supported	match (n:movie) where n.movieid > 10 return n
  order by	Supported	match (n:movie) return n order by n.genres
  skip	Supported	match (n:movie) return n order by n.genres skip 5
  limit	Supported	match (n:movie) return n order by n.genres skip 5 limit 10
  create	Supported	create (n:user{_ID_: 'Jack' }) return n
  delete	Supported	match (n:movie)<-[r]-(m:user) delete r
  set	Supported	match (n:user{userid:0}) set n.gender='M' return n
  call procedures	Supported	call db.schema()
  unwind	Supported	unwind [1, 2, 3] as p return p

  

  1. Currently, union, merge, foreach, and optional operations are not supported. Cypher statements cannot be used to add or delete indexes. These operations will be supported in later versions.
  2. GES metadata is not schema-free, and the vertex and edge label properties are strictly restricted. Therefore, the remove operation is not supported.
  3. The order by clause does not support the sorting of the list type. When Cardinality of the property value is not single, the sorting result is unknown.
• Parameterized queries

  Cypher supports parameterized query. The value types such as numeric and character string in the query statement are extracted as parameters to accelerate the compilation of the query, thereby improving the query speed.

  The following provides several examples of parameterized queries:

  • Parameterized query request example 1

    POST http://{SERVER_URL}/ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=execute-cypher-query
    {
             "statements": [{
                       "statement": " match (n:user) where n.occupation = $occupation return n",
                       "parameters": {
                             "occupation" : "artist"
                        },
                       "resultDataContents": ["row"]
             }]
    }

  • Parameterized query request example 2

    POST http://{SERVER_URL}/ges/v1.0/{project_id}/graphs/{graph_name}/action?action_id=execute-cypher-query
    {
             "statements": [{
                       "statement": " match (n:user {`Zip-code`:'98133'}) set n = $props return n",
                       "parameters": {
                               "props": {
                               "gender": "M",
                               "age": "56+"
                            }
                        },
                       "resultDataContents": ["row"]
             }]
    }

  

  Parameterized queries do not apply to the following scenarios, where the following query statements cannot be executed properly:

  • Property key value, for example, match (n) where n.$param = 'something'
  • Vertex label, for example, match (n:user) set n:$code
• Supported data types

  Currently, GES supports 10 data types: char, char_array, float, double, Boolean, long, Integer, date, enum, and string. Both Boolean and numeric types are supported in the Cypher syntax. The mapping between other types and Cypher is as follows:

  Table 10 Mapping between types of GES and Cypher

  GES Type	Cypher type	Description
  char	String	-
  char_array	String	-
  string	String	-
  enum	String	The Cypher syntax does not provide the enumeration-related syntax. During Cypher query, enum is output as a string. When Cypher is used to set properties, values that are not in the enumeration list fail to be set.
  date	Temporal	Currently, dates can be input and output in the GES date format, but cannot be input by calling the Cypher date function.

  Table 11 Special types supported by Cypher

  Type	Support	Example
  Node	Supported	match (n) return n limit 10
  Relationship	Supported	match (n)-[r]->(m) return r limit 10
  List	Supported	return [1,2,3] as li
  Map	Supported	match (n)-->(m) return {start:id(n), end:id(m)}
  Path	Supported	match p=(n1)-[:friends*1..2]-(n2) return p limit 10
  Point, Spatial	Not supported	-

  

  For the special types listed in Special types supported by Cypher, only the list type is used to match multi-value properties in GES. Other types cannot be set to the value of a property of a vertex or edge by using the set statement.

• Expressions

  The where clause in Cypher queries supports multiple expressions, which can be combined to form various filter criteria. Currently, the following expressions are supported:

  Operation Type	Expression	Example
  Logical operations	and	match (n:user) where n.age='Under 18' and n.gender='F' return n
  	or	match(n:user) where n.`Zip-code`='22181' or n.userid=6 return n
  	not	match(n:movie) where not n.genres contains 'Drama' return n
  Null value judgment	is null	match (n) where n.userid is null return n
  	is not null	match (n) where n.userid is not null return n
  Comparison calculation	>,>=,<,<=,=,<>	match(n:user) where n.userid>=5 return n
  String comparisons	starts with	match(n:movie) where n.genres starts with 'Comedy' return n
  	ends with	match(n:movie) where n.genres ends with 'Drama' return n
  	contains	match(n:movie) where n.genres contains 'Drama' return n
  List-related operation	in	match(n:student) where 'math' in n.courses return n
  	[]	match(n:user) return n[' userid'] with [1, 2, 3, 4] as list return list[0] with [1, 2, 3, 4] as list return list[0..1] match p=(n)-->(m) return [x in nodes(p) where x.gender='F'|id(x)]

  

  The where clause in Cypher queries does not support case expressions, arithmetic operators, and regular expression matching.

• Functions and procedures
  • Function

  During grouping, aggregation, and vertex and edge operations, Cypher supports a series of functions. Currently, the following functions are supported:

  1. Aggregate function
     Currently, the count and collect aggregate functions are supported.

     Function	Description	Example
     count	Returns the total number of results.	match (n) return count(*) match (n) return count(n.userid)
     collect(2.2.17)	Collects results in a list.	match (n:movie) return n.genres, collect(n) as movieList

  2. Common function

     Based on the types of input parameters, common functions are classified into vertex and edge functions, path functions, list functions, and value functions.

     Table 12 Vertex and edge functions

     Function	Description	Example
     id	Obtains the ID of a vertex.	match (n) return id(n)
     labels	Obtains labels of a vertex.	match (n) return labels(n)
     type	Obtains the label of an edge.	match(n)-[r]->(m) return type(r)

     Table 13 Path functions (2.2.19)

     Function	Description	Example
     nodes	Obtains the list of vertices on a path.	match p=(n)-[:friends*1..2]->(m) return nodes(p)
     relationships	Obtains the list of edges on a path.	match p=(n)-[:friends*1..2]->(m) return relationships(p)
     length	Obtains the path length.	match p=(n)-[:friends*1..2]->(m) return length(p)

     Table 14 List functions

     Function	Description	Example
     head	Obtains the first element of a list.	with [1,2,3,4] as list return head(list)
     last	Obtains the last element of a list.	with [1,2,3,4] as list return last(list)
     size	Obtains the list length.	with [1,2,3,4] as list return size(list)

     Table 15 Value functions

     Function	Description	Example
     toString(2.2.21)	Converts a value to a string.	match (n) where toString(labels(n)) contains 'movi' return n

     Table 16 Predicate functions (2.2.19)

     Function	Description	Example
     all	If all elements meet the expression, true is returned.	all (x in p where x>1)
     any	If any element meets the expression, true is returned.	any (x in p where x>1)
     none	If all elements cannot meet the expression, true is returned.	none (x in p where x>1)
     single	If only one element meets the expression, true is returned.	single (x in p where x>1)

     

     • Aggregate functions such as avg(), max(), and min(), and mathematical functions such as sin() and cos(), will be available in later versions.
     • Procedure

       Currently, GES supports the following procedures.

       Procedure	Statement
       Obtaining graph mode information	call db.schema()
       Obtaining vertex labels	call db.labels()
       Obtaining edge labels	call db.relationshipTypes()
       Querying the Cypher statements that are being executed	call dbms.listQueries()
       Terminating a Cypher statement based on queryId	call dbms.killQuery('queryId')

• Vertex ID compatibility
  • Cypher does not provide the syntax for setting the ID when a vertex is added. In GES, an ID of the character string type is required to uniquely identify a vertex. To be compatible with the Cypher syntax, the current create statement uses a special identifier _ID_ to specify the ID of a vertex. For example, the create(n{_ID_:'123456'}) statement creates a vertex whose ID is 123456.
  • If the ID is not specified, a random ID is generated for the vertex.
    

    The _ID_ identifier is supported only in the create statement. The match and set clauses do not support the _ID_ identifier. In the match clause, you can use the id() function to obtain the vertex ID.

• Parallel edge processing policy in vertex adding

  When using Cypher to add edges, you can add duplicate edges. The duplicate edges are defined as two edges with the same source vertex and target vertex.