apoc.custom.declareFunction

Procedure APOC Full

apoc.custom.declareFunction(signature, statement, forceSingle, description) - register a custom cypher function

Signature

apoc.custom.declareFunction(signature :: STRING?, statement :: STRING?, forceSingle = false :: BOOLEAN?, description =  :: STRING?) :: VOID

This procedure is not intended to be used in a cluster environment, and may act unpredictably.

Input parameters

Name Type Default

signature

STRING?

null

statement

STRING?

null

forceSingle

BOOLEAN?

false

description

STRING?

Usage Examples

Here is a simple example:

CALL apoc.custom.declareFunction('answerFun() :: INT', 'RETURN 42 as answer')

This registers the statement as procedure custom.answer that you then can call.

RETURN custom.answerFun()
Table 1. Results
answer

42

Or you can also write in this way:

CALL apoc.custom.declareFunction('answerFunMap() :: MAP', 'RETURN 42 as answer')

In this case the result is wrapped in a map of key answer and value 42. Therefore, you can do:

RETURN custom.answerFunMap() AS row
Table 2. Results
row

{ "answer": 42 }

In case you return a map, you can choose to wrap the result in another map with key the name of the result, and value the value obtained. For example, declaring this function:

CALL apoc.custom.declareFunction('answerFunMap(value:: INT) :: MAP', 'RETURN {a: $value}')

you can execute:

return custom.answerFunMap(2) as row
Table 3. Results
row
{
    "{a: $value}":
    {"a": 2}
  }

Note that the {"a": 2} is wrapped by a map with key {a: $value}", that is the column name which would be returned from the RETURN {a: $value}

Instead, using MAPRESULT:

CALL apoc.custom.declareFunction('answerFunMapResult(value:: INT) :: MAPRESULT', 'RETURN $value')

you can execute:

RETURN custom.answerFunMapResult(2) AS row
Table 4. Results
row
{"a": 2}

which is equivalent to deprecated one:

CALL apoc.custom.asFunction('answer','RETURN 42 as answer')

We can create the function custom.powers that returns a stream of the powers of the first parameter, up to and including the power provided by the second parameter:

CALL apoc.custom.declareProcedure(
  'powers(input::INT, power::INT) :: (answer::INT)',
  'UNWIND range(0, $power) AS power
   RETURN $input ^ power AS answer'
);

We can create the function custom.double, that doubles the provided value, by running the following function:

CALL apoc.custom.declareFunction(
  'double(input::INT) :: INT',
  'RETURN $input*2 as answer'
);
Function, input and output names must have at least 2 characters.

We can use this function, as shown in the query below:

RETURN custom.double(83) AS value;
Table 5. Results
value

166

Furthermore, we can pass as a 3rd parameter a boolean (with default false) which, if true, in case the function returns a list of a single element, it will return only the single element itself and not the list.

For example:

CALL apoc.custom.declareFunction('forceSingleTrue(input::ANY) :: LIST OF INT',
  'RETURN 1',
  true
);
Table 6. Results
value

1

otherwise with false the result will be a singleton list:

CALL apoc.custom.declareFunction('forceSingleFalse(input::ANY) :: LIST OF INT',
  'RETURN 1',
  false
);
Table 7. Results
value

[1]

Moreover, we can pass a description parameter as the 4th parameter, which will be returned by the call apoc.custom.list and SHOW FUNCTIONS.