CALL procedure

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

Introduction

Procedures are called using the CALL clause.

The CALL clause is also used to evaluate a subquery. For descriptions of the CALL clause in this context, refer to CALL {} (subquery).

Each procedure call needs to specify all required procedure arguments. This may be done either explicitly, by using a comma-separated list wrapped in parentheses after the procedure name, or implicitly by using available query parameters as procedure call arguments. The latter form is available only in a so-called standalone procedure call, when the whole query consists of a single CALL clause.

Most procedures return a stream of records with a fixed set of result fields, similar to how running a Cypher® query returns a stream of records. The YIELD sub-clause is used to explicitly select which of the available result fields are returned as newly-bound variables from the procedure call to the user or for further processing by the remaining query. Thus, in order to be able to use YIELD for explicit columns, the names (and types) of the output parameters need be known in advance. Each yielded result field may optionally be renamed using aliasing (i.e., resultFieldName AS newName). All new variables bound by a procedure call are added to the set of variables already bound in the current scope. It is an error if a procedure call tries to rebind a previously bound variable (i.e., a procedure call cannot shadow a variable that was previously bound in the current scope). In a standalone procedure call, YIELD * can be used to select all columns. In this case, the name of the output parameters does not need to be known in advance.

For more information on how to determine the input parameters for the CALL procedure and the output parameters for the YIELD procedure, see View the signature for a procedure.

Inside a larger query, the records returned from a procedure call with an explicit YIELD may be further filtered using a WHERE sub-clause followed by a predicate (similar to WITH ... WHERE ...).

If the called procedure declares at least one result field, YIELD may generally not be omitted. However YIELD may always be omitted in a standalone procedure call. In this case, all result fields are yielded as newly-bound variables from the procedure call to the user.

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 and that has explicitly been declared as VOID. Calling a VOID procedure may only have a side effect and thus does neither allow nor require 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).

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.

Call a procedure using CALL

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

Query
CALL db.labels()
Table 1. Result
label

"User"

"Administrator"

Rows: 2

Cypher allows the omission of parentheses on procedures of arity-0 (no arguments).

Best practice is to use parentheses for procedures.
Query
CALL db.labels
Table 2. Result
label

"User"

"Administrator"

Rows: 2

View the signature for a procedure

The SHOW PROCEDURES command can return the name, signature, and description for all procedures.

The default outputs for SHOW PROCEDURES are name, description, mode, and worksOnSystem. To get the signature, make sure to use the YIELD clause.

Example 1. SHOW PROCEDURES

The following query return the signature for a particular procedure:

Query
SHOW PROCEDURES YIELD name, signature
WHERE name = 'dbms.listConfig'
RETURN signature
Table 3. Result
signature

"dbms.listConfig(searchString = :: STRING) :: (name :: STRING, description :: STRING, value :: STRING, dynamic :: BOOLEAN, defaultValue :: STRING, startupValue :: STRING, explicitlySet :: BOOLEAN, validValues :: STRING)"

Rows: 1

Call a procedure using a quoted namespace and name

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

Query
CALL db.labels()
Query
CALL db.labels

Call a procedure with literal arguments

This calls the example procedure dbms.checkConfigValue using literal arguments. The arguments are written out directly in the statement text.

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

true

"requires restart"

Call a procedure with parameter arguments

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).

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.
Parameters
{
  "setting": "server.bolt.enabled",
  "value": "true"
}
Query
CALL dbms.checkConfigValue($setting, $value)
Table 5. Result
"valid" "message"

true

"requires restart"

Cypher allows the omission of parentheses for procedures with arity-n (n arguments), Cypher implicitly passes the parameter arguments.

Best practice is to use parentheses for procedures. Omission of parentheses is available only in a so-called standalone procedure call, when the whole query consists of a single CALL clause.
Parameters
{
  "setting": "server.bolt.enabled",
  "value": "true"
}
Query
CALL dbms.checkConfigValue
Table 6. Result
"valid" "message"

true

"requires restart"

Call a procedure with mixed 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 7. Result
"valid" "message"

true

"requires restart"

Call a procedure with literal and default arguments

This calls the example procedure dbms.checkConfigValue using literal arguments. That is, arguments that are written out directly in the statement text, and a trailing default argument that is provided by the procedure itself.

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

true

"requires restart"

Call a procedure using CALL YIELD *

This calls the built-in procedure db.labels to count all labels used in the database.

Query
CALL db.labels() YIELD *

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

Call a procedure within a complex query using CALL YIELD

This calls the built-in procedure db.labels to count all labels used in the database.

Query
CALL db.labels() YIELD label
RETURN count(label) AS numLabels

Since the procedure call is part of a larger query, all outputs must be named explicitly.

Call a procedure and filter its results

This calls the built-in procedure db.labels to count all in-use labels in the database that contain the string 'User'.

Query
CALL db.labels() YIELD label
WHERE label CONTAINS 'User'
RETURN count(label) AS numLabels

Since the procedure call is part of a larger query, all outputs must be named explicitly.

Call a procedure within a complex query and rename its outputs

This calls the built-in procedure db.propertyKeys as part of counting the number of nodes per property key that is currently used in the database.

Query
CALL db.propertyKeys() YIELD propertyKey AS prop
MATCH (n)
WHERE n[prop] IS NOT NULL
RETURN prop, count(n) AS numNodes

Since the procedure call is part of a larger query, all outputs must be named explicitly.