call.adoc

CALL procedure

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

Note	The CALL clause is also used to evaluate a subquery. For more information about the CALL clause in this context, refer to :subqueries/call-subquery.adoc.

For information about how to list procedures, see clauses/listing-procedures.adoc.

Note	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:

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

Note	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"

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"

Note	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 :syntax/parameters.adoc 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"

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. 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 returned by a SHOW PROCEDURES query.

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

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