CALL procedure

The CALL clause is used to call a procedure deployed in the database.

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

For information about how to list procedures, see SHOW PROCEDURES.

Neo4j comes with a number of built-in procedures. For a list of these, see Operations Manual → Procedures. Users can also develop custom procedures and deploy to the database. See Java Reference → User-defined procedures for details.

Example graph

The following graph is used for the examples below:

call procedure

To recreate it, run the following query 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)

Examples

Example 1. CALL a procedure without arguments

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

Query
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, when the whole query consists of a single CALL clause.
Example 2. CALL a procedure without 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
Example 3. CALL a procedure using parameters

This calls the example 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).

Parameters
{
  "setting": "server.bolt.enabled",
  "value": "true"
}
Query
CALL dbms.checkConfigValue($setting, $value)
Table 3. Result
"valid" "message"

true

"requires restart"

Rows: 1
Examples that use parameter arguments shows the given parameters in JSON format; the exact manner in which they are to be submitted depends upon the driver being used. See Parameters for more about querying with parameters.
Example 4. CALL a procedure using both literal and parameter arguments

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

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

true

"requires restart"

Rows: 1

Using YIELD

The YIELD keyword is used to specify which columns of procedure metadata to return, allowing for the selection and filtering of the displayed information.

Example 5. YIELD *

Using YIELD * will return all available return columns for a procedure.

Query
CALL db.labels() YIELD *
Table 5. Result
label

"Administrator"

"Developer"

Rows: 2

If the procedure has deprecated return columns, those columns are also returned.

Note that YIELD * is only valid in standalone procedure calls. Variables must be explicitly named in a YIELD clause if other clauses than a single procedure CALL are present. 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
Example 6. YIELD specific procedure results 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 in the Operations Manual → Procedures or in the signature column returned by a SHOW PROCEDURES command (see example below).

Find the argument names of db.propertyKeys()
SHOW PROCEDURES YIELD name, signature
WHERE name = 'db.propertyKeys'
RETURN signature
Table 6. 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 below 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 returned by YIELD
CALL db.propertyKeys() YIELD propertyKey AS prop
MATCH (n)
WHERE n[prop] IS NOT NULL
RETURN prop, count(n) AS numNodes
Table 7. 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 will simply pass on each input record (i.e., it acts like WITH * in terms of the record stream).

Optional procedure calls
Introduced in 5.24

OPTIONAL CALL allows for an optional procedure call. Similar to OPTIONAL MATCH any empty rows produced by the OPTIONAL CALL will return null.

Example 7. Difference between using CALL and OPTIONAL CALL

This 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

Note that the result does not include the nodes in the graph without any outgoing KNOWS relationships connected to them.

Table 8. Result
name connections

"Andy"

["Beatrice", "David"]

"Beatrice"

["Charlotte"]

Rows: 2

The same query is used below, 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 now includes the two nodes without any outgoing KNOWS relationships connected to them.

Table 9. Result
name connections

"Andy"

["Beatrice", "David"]

"Beatrice"

["Charlotte"]

"Charlotte"

[]

"David"

[]

Rows: 4