CALL

Overview

The CALL statement is used to invoke an inline procedure or a named procedure.

Syntax
<call statement> ::= <call inline procedure> | <call named procedure>

Calling Inline Procedures

An inline procedure is a user-defined procedure embedded within a query, commonly used to execute subqueries or perform data modifications. It enables complex logic such as looping and enhances efficiency by managing resources more effectively, especially when working with large graphs, thereby reducing memory overhead.

Syntax
<call inline procedure> ::= 
  [ "OPTIONAL" ] "CALL" [ <variable reference list> ] <procedure specification>

<variable reference list> ：：=
  "(" <variable reference> [ { "," <variable reference> }... ] ")"

<procedure specification> ::=
  "{" <statement block> "}"

Details

• You can import variables from earlier parts of the query into CALL. If omitted, all current variables are implicitly imported.
• The imported variables are processed row by row independently inside CALL.
• When used for subqueries, the <statement block> must end with a RETURN statement to output variables to the outer query:
  • Each returned variable becomes a new column in the intermediate result table.
  • If a subquery yields no records, the associated imported record is discarded. The OPTIONAL keyword can be used to handle this case - producing a null value instead of discarding the record.
  • If multiple records are returned, the imported row is duplicated accordingly.
• For data modification procedures, a RETURN statement is not required. In such cases, the number of records in the intermediate result table remains the same after CALL.

Example Graph

GQL
INSERT (rowlock:User {_id:'U01', name:'rowlock'}),
       (brainy:User {_id:'U02', name:'Brainy'}),
       (purplechalk:User {_id:'U03', name:'purplechalk'}),
       (mochaeach:User {_id:'U04', name:'mochaeach'}),
       (lionbower:User {_id:'U05', name:'lionbower'}),
       (c01:Club {_id:'C01'}),
       (c02:Club {_id:'C02'}),
       (rowlock)-[:Follows]->(brainy),
       (mochaeach)-[:Follows]->(brainy),
       (brainy)-[:Follows]->(purplechalk),
       (lionbower)-[:Follows]->(purplechalk),
       (brainy)-[:Joins]->(c01),
       (lionbower)-[:Joins]->(c01),
       (brainy)-[:Joins]->(c02),
       (mochaeach)-[:Joins]->(c02)

Subqueries

Find members of each club:

GQL
MATCH (c:Club)
CALL {
    MATCH (c)<-[:Joins]-(u:User)
    RETURN collect_list(u.name) AS members
}
RETURN c._id, members

Result:

OPTIONAL CALL

Retrieve the followers of each member in club C01, ensure that members with no followers are still included in the results:

GQL
MATCH (c)<-[:Joins]-(u:User) WHERE c._id = "C01"
OPTIONAL CALL (u) {
  MATCH (u)<-(follower:User)
  RETURN collect_list(follower.name) AS followers
}
RETURN u.name, followers

Result:

Execution Order of Subqueries

The order in which the subquery executed is not determined. If a specific execution order is desired, ORDER BY should be used to sort the records before CALL to enforce that sequence.

This query counts the number of followers for each user. The execution order of the subqueries is determined by the ascending order of the users' name:

GQL
MATCH (u:User)
ORDER BY u.name
CALL {
  MATCH (u)<-[:Follows]-(follower)
  RETURN count(follower) AS followersNo
}
RETURN u.name, followersNo

Result:

Data Modifications

Set values for the property rates of Joins edges:

GQL
FOR score IN [1,2,3,4]
CALL {
    MATCH ()-[e:Joins WHERE e.rates IS NULL]-() LIMIT 1  
    SET e.rates = score
    RETURN e
}
RETURN e

Result:

JSON
[
  {"id": "e:7", "label": "Joins", "fromNodeId": "U02", "toNodeId": "C02", "properties": {"rates": 1}},
  {"id": "e:8", "label": "Joins", "fromNodeId": "U04", "toNodeId": "C02", "properties": {"rates": 2}},
  {"id": "e:5", "label": "Joins", "fromNodeId": "U02", "toNodeId": "C01", "properties": {"rates": 3}},
  {"id": "e:6", "label": "Joins", "fromNodeId": "U05", "toNodeId": "C01", "properties": {"rates": 4}}
]

Calling Named Procedures

A named procedure refers to a predefined procedure, such as an algorithm, that is registered in the system and can be invoked by its name using the CALL statement.

Syntax
<call named procedure> ::= [ "OPTIONAL" ] "CALL" <procedure reference> [ <yield clause> ]

<yield clause> ::= "YIELD" <yield item> [ { "," <yield item> }... ]

<yield item> ::= <column name> [ "AS" <binding variable> ]

Details

• The YIELD clause can be used to output variables to the outer query.
• Prefix with OPTIONAL to keep rows from the outer query even when the procedure produces no results (the yielded columns are bound to NULL for those rows).

Running an Algorithm

The following query executes the Degree Centrality algorithm:

GQL
CALL algo.degree({
  order: "desc"
}) YIELD nodeId, degree

To learn more about available algorithms, refer to the Graph Algorithms documentation.

OPTIONAL CALL

OPTIONAL CALL <namedProcedure>(...) mirrors the inline OPTIONAL CALL { ... } form: the outer rows are preserved even when the named procedure yields nothing, and the yielded columns become NULL for those rows.

GQL
OPTIONAL CALL algo.degree({
  ids: ["A", "B"]
}) YIELD degree