Call procedures

The CALL clause is used to call a procedure deployed in the database. Neo4j comes with a number of built-in procedures. Users can also develop custom procedures and deploy to the database. For more details, see Java Reference → User-defined procedures.

The CALL clause is also used to evaluate a subquery. For more information about the CALL clause in this context, refer to the Cypher Manual → CALL subquery.

Example graph

The examples on this page use the following graph:

Example graph connecting people in the roles of developer and administrator

To recreate it, run the following statement against an empty Neo4j database:

CREATE (andy:Developer {name: 'Andy', born: 1991}),
       (beatrice:Developer {name: 'Beatrice', born: 1985}),
       (charlotte:Administrator {name: 'Charlotte', born: 1990}),
       (david:Administrator {name: 'David', born: 1994, nationality: 'Swedish'}),
       (andy)-[:KNOWS]->(beatrice),
       (beatrice)-[:KNOWS]->(charlotte),
       (andy)-[:KNOWS]->(david)

Standalone procedure calls

A Cypher statement made up of only a single CALL clause is known as a standalone procedure call.

Call a procedure without arguments

This example calls the built-in procedure db.labels(), which lists all labels used in the database.

Procedure call
CALL db.labels()
Table 1. Result
label

"Developer"

"Administrator"

Rows: 2

It is best practice to use parentheses when calling procedures, although Cypher allows for their omission when calling procedures of arity-0 (no arguments). Omission of parentheses is available only in a so-called standalone procedure call.

Call a procedure using literal arguments

This example calls the procedure dbms.checkConfigValue(), which checks the validity of a configuration setting value, using literal arguments.

Query
CALL dbms.checkConfigValue('server.bolt.enabled', 'true')
Table 2. Result
"valid" "message"

true

"requires restart"

Rows: 1

Call a procedure using parameters

This example calls the procedure dbms.checkConfigValue() using parameters as arguments. Each procedure argument is taken to be the value of a corresponding statement parameter with the same name (or null if no such parameter has been given).

The below example shows the given parameters in JSON format; the exact manner in which they are to be submitted depends on the driver being used. For more information, see the Cypher Manual → Parameters.
Parameters
{
  "setting": "server.bolt.enabled",
  "value": "true"
}
Procedure call
CALL dbms.checkConfigValue($setting, $value)
Table 3. Result
"valid" "message"

true

"requires restart"

Rows: 1

Call a procedure using both literal and parameter arguments

This example calls the procedure dbms.checkConfigValue() using both literal and parameter arguments.

Parameters
{
  "setting": "server.bolt.enabled"
}
Procedure call
CALL dbms.checkConfigValue($setting, 'true')
Table 4. Result
"valid" "message"

true

"requires restart"

Rows: 1

Using YIELD to specify return columns and filter data

The YIELD keyword is used to specify which procedure columns to return, allowing for the selection and filtering of the displayed information. YIELD is necessary if the procedure call is part of a larger Cypher statement (i.e. not a standalone procedure call).

YIELD * is only valid in standalone procedure calls and only adds the ability to show deprecated return columns (there are no non-default return columns for called procedures).

When YIELD is used outside of a standalone procedure call, variables must be explicitly named. This restriction simplifies query logic and protects against output variables from the procedure accidentally clashing with other query variables. For example, the following is not valid:

Not allowed
CALL db.labels() YIELD *
RETURN count(*) AS results

Yield specific return columns and filter on them

YIELD can be used to filter for specific results. This requires knowing the names of the arguments within a procedure’s signature, which can either be found on the built-in procedures page or in the signature column returned by a SHOW PROCEDURES command.

Find the argument names of db.propertyKeys()
SHOW PROCEDURES YIELD name, signature
WHERE name = 'db.propertyKeys'
RETURN signature
Table 5. Result
signature

"db.propertyKeys() :: (propertyKey :: STRING)"

Rows: 1

It is then possible to use these argument names for further query filtering. Note that if the procedure call is part of a larger query, its output must be named explicitly. In the following example, propertyKey is aliased as prop and then used later in the query to count the occurrence of each property in the graph.

Filter on specific argument
CALL db.propertyKeys() YIELD propertyKey AS prop
MATCH (n)
WHERE n[prop] IS NOT NULL
RETURN prop, count(n) AS numNodes
Table 6. Result
prop numNodes

"name"

4

"born"

4

"nationality"

1

Rows: 3

Note on VOID procedures

Neo4j supports the notion of VOID procedures. A VOID procedure is a procedure that does not declare any result fields and returns no result records. VOID procedure only produces side-effects and does not allow for the use of YIELD.

Calling a VOID procedure in the middle of a larger query simply passes on each input record (i.e., it acts like WITH * in terms of the record stream).

CALL vs. OPTIONAL CALL

Regular procedure calls using CALL only return rows for which the procedure produces results. OPTIONAL CALL allows for an optional procedure call. Similar to OPTIONAL MATCH, any empty rows produced by OPTIONAL CALL return null.

Regular procedure call

This following query uses the apoc.neighbors.tohop() procedure (part of Neo4j’s APOC Core library), which returns all nodes connected by the given relationship type within the specified distance (1 hop, in this case) and direction.

Regular procedure call
MATCH (n)
CALL apoc.neighbors.tohop(n, "KNOWS>", 1)
YIELD node
RETURN n.name AS name, collect(node.name) AS connections

The result includes only the nodes with outgoing KNOWS relationships and their connections.

Table 7. Result
name connections

"Andy"

["Beatrice", "David"]

"Beatrice"

["Charlotte"]

Rows: 2

Optional procedure call

The same query is used in the following example, but CALL is replaced with OPTIONAL CALL.

Optional procedure call
MATCH (n)
OPTIONAL CALL apoc.neighbors.tohop(n, "KNOWS>", 1)
YIELD node
RETURN n.name AS name, collect(node.name) AS connections

The result includes the two nodes without any outgoing KNOWS relationships connected to them.

Table 8. Result
name connections

"Andy"

["Beatrice", "David"]

"Beatrice"

["Charlotte"]

"Charlotte"

[]

"David"

[]

Rows: 4