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:
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
CALL
a procedure without argumentsThis example calls the built-in procedure db.labels()
, which lists all labels used in the database.
CALL db.labels()
label |
---|
|
|
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.
|
CALL
a procedure without argumentsThis example calls the procedure dbms.checkConfigValue()
, which checks the validity of a configuration setting value, using literal arguments.
CALL dbms.checkConfigValue('server.bolt.enabled', 'true')
"valid" | "message" |
---|---|
|
|
CALL
a procedure using parametersThis 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).
{
"setting": "server.bolt.enabled",
"value": "true"
}
CALL dbms.checkConfigValue($setting, $value)
"valid" | "message" |
---|---|
|
|
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. |
CALL
a procedure using both literal and parameter argumentsThis calls the example procedure dbms.checkConfigValue()
using both literal and parameter arguments.
{
"setting": "server.bolt.enabled"
}
CALL dbms.checkConfigValue($setting, 'true')
"valid" | "message" |
---|---|
|
|
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.
YIELD *
Using YIELD *
will return all available return columns for a procedure.
CALL db.labels() YIELD *
label |
---|
|
|
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:
CALL db.labels() YIELD *
RETURN count(*) AS results
YIELD
specific procedure results and filter on themYIELD
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.
db.propertyKeys
SHOW PROCEDURES YIELD name, signature
WHERE name = 'db.propertyKeys'
RETURN signature
signature |
---|
|
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.
YIELD
CALL db.propertyKeys() YIELD propertyKey AS prop
MATCH (n)
WHERE n[prop] IS NOT NULL
RETURN prop, count(n) AS numNodes
prop | numNodes |
---|---|
|
|
|
|
|
|
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
.
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.
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.
name | connections |
---|---|
|
|
|
|
Rows: 2 |
The same query is used below, but CALL
is replaced with OPTIONAL CALL
.
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.
name | connections |
---|---|
|
|
|
|
|
|
|
|
Rows: 4 |