Performing 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.

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.

  

  In asynchronous mode (executionMode is set to 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

• 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 information in graph format. This parameter is displayed only when resultDataContents contains graph.
  raw(2.2.27)	No	List	Returns information in raw format. This parameter is displayed only when resultDataContents contains raw.

• Example of a successful synchronous 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

• Example of a successful asynchronous request

  Http Status Code: 200
  {
      "results": [
          {
              "columns": [
                  "jobId",
                  "jobType"
              ],
              "data": [
                  {
                      "row": [
                          "b64a5846-e306-4f87-b0f1-d595ee2a9910",
                          1
                      ],
                      "meta": [
                          null,
                          null
                      ]
                  }
              ]
          }
      ],
      "errors": []
  }

• 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 prerequisites are not required for graphs of the 100-billion-edge type.

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 to Cypher

• 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
  union	Supported	match (n:movie) return id(n) union match (n:user) return id(n) NOTE: Union is available for graphs smaller than 10 billion edges only.

  

  1. Currently, merge, foreach, and optional operations are not supported. Cypher statements cannot be used to add or delete indexes.
  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.
• Parameter-based queries

  Cypher supports parameter-based query. Numeric and string values in a query statement are extracted and converted to parameters for faster compilation, improving the query speed.

  There are some examples of parameterized queries:

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

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

  

  The following syntax is not valid:

  1. Using $param to search by property key and value. For example, match (n) where n.$param = 'something'
  2. Using $code for vertex and edge labels. 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. NOTE: This parameter is not supported by graphs of the 100-billion-edge type.
  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 NOTE: This parameter is not supported by graphs of the 100-billion-edge type.
  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

  Cypher queries support multiple expressions and can be used in combination 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)]This operator is not supported for graphs of the 100-billion- edge type.

  

  The where clause in Cypher queries does not support 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)
     degree(2.2.26)	Obtains the degree of a vertex.	match (n) where id='Vivian' return degree(n)
     inDegree(2.2.26)	Obtains the indegree of a vertex.	match (n) where id='Vivian' return inDegree(n)
     outDegree(2.2.26)	Obtains the outdegree of a vertex.	match (n) where id='Vivian' return outDegree(n)

     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) This function is not supported by graphs of the 100-billion-edge type.
     relationships	Obtains the list of edges on a path.	match p=(n)-[:friends*1..2]->(m) return relationships(p) This function is not supported by graphs of the 100-billion-edge type.
     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
     toUpper(2.2.26)	Converts a string into uppercase letters.	match (n:movie) return toUpper(n.title)
     toLower(2.2.26)	Converts a string into lowercase letters.	match (n:movie) return toLower(n.title)
     toInteger(2.2.29)	Converts a string to an int number.	with '123' as p return toInteger(p)
     toLong(2.2.29)	Converts a string to a long number.	with '123' as p return toLong(p)
     toFloat(2.2.29)	Converts a string to a float number.	with '123.4' as p return toFloat(p)
     toDouble(2.2.29)	Converts a string to a double number.	with '123.4' as p return toDouble(p)
     toBoolean(2.2.29)	Converts a string to a bool value.	with 'true' as p return toBoolean(p)
     size(2.2.29)	Obtains the string length.	with 'GES' as p return size(p)

     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)

     Table 17 Algorithm expression (2.3.2)

     Function	Description	Example
     shortestPath	Returns the shortest path between two vertices.	The following expression returns the shortest path between the given vertices n and m. The direction is m to n, and the edge label is rate: with n,m, shortestPath((n)<-[:rate*]-(m)) as p return p
     allShortestPaths	Returns all shortest paths between two vertices.	The following expression returns all shortest paths between the given vertices n and m: with n,m, allShortestPaths((n)-[*]-(m)) as p return p

     

     • Aggregate functions, such as sum(), avg(), max(), and min(), are not available for 100-billion-edge graphs. Mathematical functions, such as sin() and cos(), will be available in the future.
     • 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() This procedure is not supported by graphs of the 100-billion-edge type.
       Querying the Cypher statements that are being executed	call dbms.listQueries()
       Terminating a Cypher statement based on queryId	call dbms.killQuery('queryId')

       

       Function and procedure names are case sensitive and must be in lower camel case.

• 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

  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.

• How to add an edge without a label

  When you use a Cypher statement to add an edge, set the label of the edge to the default value __DEFAULT__. For example, create ()-[r:__DEFAULT__]->() return r.

Querying the Schema Structure Using Cypher

• Function

  This API is used to query the structure of the generated schema (obtained from OBS).

• Query statement
  • Name: Schema structure query
  • Command: call db.schema ()
  • Note:

    If you did not call the API for generating the schema structure, this API returns all labels in the schema file.

    If you have called the API for generating the schema structure, this API returns the labels as the vertices and the relationships between the labels as edges.