From a9076ccf4eaeb23795364fa108f7b36914f0f34d Mon Sep 17 00:00:00 2001 From: Giuseppe Villani Date: Wed, 18 May 2022 15:52:56 +0200 Subject: [PATCH 1/3] Fixes #2895: update apoc.custom.* documentation --- .../cypher-based-procedures-functions.adoc | 180 ++++++++++-------- .../usage/apoc.custom.declareFunction.adoc | 101 +++++++++- .../usage/apoc.custom.declareProcedure.adoc | 63 +++++- 3 files changed, 266 insertions(+), 78 deletions(-) diff --git a/docs/asciidoc/modules/ROOT/pages/cypher-execution/cypher-based-procedures-functions.adoc b/docs/asciidoc/modules/ROOT/pages/cypher-execution/cypher-based-procedures-functions.adoc index d245da8b79..733b87e9fd 100644 --- a/docs/asciidoc/modules/ROOT/pages/cypher-execution/cypher-based-procedures-functions.adoc +++ b/docs/asciidoc/modules/ROOT/pages/cypher-execution/cypher-based-procedures-functions.adoc @@ -7,55 +7,23 @@ I wanted for a long time to be able to register Cypher statements as proper procedures and functions, so that they become callable in a standalone way. -You can achieve that with the `apoc.custom.asProcedure` and `apoc.custom.asFunction` procedure calls. +You can achieve that with the `apoc.custom.declareProcedure` and `apoc.custom.declareFunction` procedure calls. Those register a given Cypher statement, prefixed with the `custom.*` namespace, overriding potentially existing ones, so you can redefine them as needed. -Here is a simple example: +NOTE: APOC provides also xref::overview/apoc.custom/apoc.custom.asFunction.adoc[apoc.custom.asFunction] and xref::overview/apoc.custom/apoc.custom.asProcedure.adoc[apoc.custom.asProcedure] procedures, +but they have been deprecated in favor of `apoc.custom.declare*`s. -[source,cypher] ----- -CALL apoc.custom.asProcedure('answer','RETURN 42 as answer') ----- - -This registers the statement as procedure `custom.answer` that you then can call. -As no information on parameter and return types is given, it just returns a stream of columns of maps called `row`. - -[source,cypher] ----- -CALL custom.answer YIELD row -RETURN row.answer ----- - -The same is possible as a function: - -[source,cypher] ----- -CALL apoc.custom.asFunction('answer','RETURN 42') ----- -NOTE: If you override procedures or functions you might need to call `call dbms.clearQueryCaches()` as lookups to internal id's are kept in compiled query plans. +The first parameter of the `apoc.custom.declareProcedure` and `apoc.custom.declareFunction` procedures, +is the signature of the procedure/function you want to create. +This looks similar to the `signature` results returned by the `SHOW PROCEDURES YIELD signature` and `SHOW FUNCTIONS YIELD signature` cypher commands, +that is: +- for a procedure: `nameProcedure(firstParam = defaultValue :: typeParam , secondParam = defaultValue :: typeParam, ....) :: (firstResult :: typeResult, secondResult :: typeResult, ... )` +- for a function: `nameFunction(firstParam = defaultValue :: typeParam , secondParam = defaultValue :: typeParam, ....) :: typeResult` -== Custom Procedures with `apoc.custom.asProcedure` +Note that, for both procedures and functions, the `= defaultValue` are optionals. -Given statement will be registered as a procedure, the results will be turned into a stream of records. - -.Parameters -[%autowidth,opts=header,cols="m,m,a"] -|=== -| name -| default -| description - -| name | none | dot-separated name, will be prefixed with `custom` -| statement | none | cypher statement to run, can use $parameters -| mode | read | execution mode of the procedure: read, write, or schema -| outputs | [["row","MAP"]] | List of pairs of name-type to be used as output columns, need to be in-order with the cypher statement, the default is a special case, that will collect all columns of the statement result into a map -| inputs | [["params","MAP","{}"]] | Pairs or triples of name-type-default, to be used as input parameters. The default just takes an optional map, otherwise they will become proper paramters in order -| description | "" | A general description about the business rules implemented into the procedure -|=== - -The type names are what you would expect and see in outputs of `dbms.procedures` or `apoc.help` just without the `?`. -The default values are parsed as JSON. +The `type`s are what you would expect and see in outputs of `SHOW PROCEDURES`, `SHOW FUNCTIONS` or `apoc.help` just without the `?`. .Type Names * FLOAT, DOUBLE, INT, INTEGER, NUMBER, LONG @@ -68,47 +36,23 @@ The default values are parsed as JSON. * LIST TYPE, LIST OF TYPE (where `TYPE` can be one of the previous values) * ANY -.Find neighbours of a node by name -[source,cypher] ----- -CALL apoc.custom.asProcedure('neighbours', - 'MATCH (n:Person {name:$name})-->(nb) RETURN nb as neighbour','read', - [['neighbour','NODE']],[['name','STRING']], 'get neighbours of a person'); - -CALL custom.neighbours('Keanu Reeves') YIELD neighbour; ----- +NOTE: If you override procedures or functions you might need to call `call db.clearQueryCaches()` as lookups to internal id's are kept in compiled query plans. -== Custom Functions with `apoc.custom.asFunction` -Given statement will be registered as a statement, the results into a single value. -If the given output type is a list, results will be collected into a list, otherwise the first row will be used. -The statement needs to return a single column, otherwise an error is thrown. +== Custom Procedures with `apoc.custom.declareProcedure` -.Parameters -[%autowidth,opts=header, cols="m,m,a"] -|=== -| name -| default -| description +include::partial$usage/apoc.custom.declareProcedure.adoc[] -| name | none | dot-separated name, will be prefixed with `custom` -| statement | none | cypher statement to run, can use $parameters -| outputs | "LIST OF MAP" | Output type for single output, if the type is a list, then all rows will be collected, otherwise just the first row. Only single column results are allowed. -If your single row result is a list you can force a single row by setting the last parameter to `true` -| inputs | [["params","MAP","{}"]] | Pairs or triples of name-type-default, to be used as input parameters. The default just takes an optional map, otherwise they will become proper paramters in order -| singleRow | false | If set to true, the statement is treated as single row even with the list result type, then your statement has to return a list. -| description | "" | A general description about the business rules implemented into the function -|=== +== Custom Functions with `apoc.custom.declareFunction` -The type names are what you would expect and see in outputs of `dbms.procedures` or `apoc.help` just without the `?`. -The default values are parsed as JSON. +include::partial$usage/apoc.custom.declareFunction.adoc[] == List of registered procedures/function with `apoc.custom.list` -The procedure `apoc.custom.list` provide a list of all registered procedures/function via -`apoc.custom.asProcedure` and `apoc.custom.asFunction` +The procedure `apoc.custom.list` provide a list of all registered procedures/function via +`apoc.custom.declareProcedure` and `apoc.custom.declareFunction`, `apoc.custom.asProcedure` and `apoc.custom.asFunction`. Given the this call: @@ -117,7 +61,7 @@ Given the this call: CALL apoc.custom.list ---- -The the output will look like the following table: +The output will look like the following table: [%autowidth,opts=header] |=== @@ -186,4 +130,88 @@ changes to each cluster member ==== To import custom procedures in another database (for example after a `./neo4j-admin backup` and `/neo4j-admin restore`), please see the xref::overview/apoc.systemdb/apoc.systemdb.export.metadata.adoc[apoc.systemdb.export.metadata] procedure. -==== \ No newline at end of file +==== + + +== [DEPRECATED] Custom Procedures with `apoc.custom.asProcedure` + +Here is a simple example: + +[source,cypher] +---- +CALL apoc.custom.asProcedure('answer','RETURN 42 as answer') +---- + +This registers the statement as procedure `custom.answer` that you then can call. +As no information on a parameter and return types is given, it just returns a stream of columns of maps called `row`. + +[source,cypher] +---- +CALL custom.answer() YIELD row +RETURN row.answer +---- + +Given statement will be registered as a procedure, the results will be turned into a stream of records. + +.Parameters +[%autowidth,opts=header,cols="m,m,a"] +|=== +| name +| default +| description + +| name | none | dot-separated name, will be prefixed with `custom` +| statement | none | cypher statement to run, can use $parameters +| mode | read | execution mode of the procedure: read, write, or schema +| outputs | [["row","MAP"]] | List of pairs of name-type to be used as output columns, need to be in-order with the cypher statement, the default is a special case, that will collect all columns of the statement result into a map +| inputs | [["params","MAP","{}"]] | Pairs or triples of name-type-default, to be used as input parameters. The default just takes an optional map, otherwise they will become proper paramters in order +| description | "" | A general description about the business rules implemented into the procedure +|=== + +The type names can be the same as `apoc.custom.declare*` analogues. +The default values are parsed as JSON. + +.Find neighbours of a node by name +[source,cypher] +---- +CALL apoc.custom.asProcedure('neighbours', + 'MATCH (n:Person {name:$name})-->(nb) RETURN nb as neighbour','read', + [['neighbour','NODE']],[['name','STRING']], 'get neighbours of a person'); + +CALL custom.neighbours('Keanu Reeves') YIELD neighbour; +---- + + + +== [DEPRECATED] Custom Functions with `apoc.custom.asFunction` + +The same is possible as a function: + +[source,cypher] +---- +CALL apoc.custom.asFunction('answer','RETURN 42') +---- + +Given statement will be registered as a statement, the results into a single value. +If the given output type is a list, results will be collected into a list, otherwise the first row will be used. +The statement needs to return a single column, otherwise an error is thrown. + +.Parameters +[%autowidth,opts=header, cols="m,m,a"] +|=== +| name +| default +| description + +| name | none | dot-separated name, will be prefixed with `custom` +| statement | none | cypher statement to run, can use $parameters +| outputs | "LIST OF MAP" | Output type for single output, if the type is a list, then all rows will be collected, otherwise just the first row. Only single column results are allowed. +If your single row result is a list you can force a single row by setting the last parameter to `true` +| inputs | [["params","MAP","{}"]] | Pairs or triples of name-type-default, to be used as input parameters. The default just takes an optional map, otherwise they will become proper parameters in order +| singleRow | false | If set to true, the statement is treated as single row even with the list result type, then your statement has to return a list. +| description | "" | A general description about the business rules implemented into the function +|=== + +The type names are what you would expect and see in outputs of `dbms.procedures` or `apoc.help` just without the `?`. +The default values are parsed as JSON. + diff --git a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareFunction.adoc b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareFunction.adoc index 4eae2ef456..99338b61ee 100644 --- a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareFunction.adoc +++ b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareFunction.adoc @@ -1,3 +1,64 @@ +Here is a simple example: + +[source,cypher] +---- +CALL apoc.custom.declareFunction('answerFun() :: INT', 'RETURN 42 as answer') +---- + +This registers the statement as procedure `custom.answer` that you then can call. +[source,cypher] +---- +RETURN custom.answerFun() +---- + +.Results +[opts="header"] +|=== +| answer +| 42 +|=== + +Or you can also write in this way: + +[source,cypher] +---- +CALL apoc.custom.declareFunction('answerFunMap() :: MAP', 'RETURN 42 as answer') +---- + +In this case the result is wrapped in a stream of maps called `row`. Therefore, you can do: + +[source,cypher] +---- +WITH custom.answerFunMap() YIELD row +RETURN row.answer +---- + +.Results +[opts="header"] +|=== +| answer +| 42 +|=== + +which is equivalent to deprecated one: + +[source,cypher] +---- +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: + +[source,cypher] +---- +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: [source,cypher] @@ -24,4 +85,42 @@ RETURN custom.double(83) AS value; | 166 |=== -If we don't need fine grained control over our function's signature, see xref::overview/apoc.custom/apoc.custom.asFunction.adoc[]. \ No newline at end of file +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: + +[source,cypher] +---- +CALL apoc.custom.declareFunction('forceSingleTrue(input::ANY) :: LIST OF INT', + 'RETURN 1', + true +); +---- + +.Results +[opts="header"] +|=== +| value +| 1 +|=== + +otherwise with false the result will be a singleton list: + +[source,cypher] +---- +CALL apoc.custom.declareFunction('forceSingleFalse(input::ANY) :: LIST OF INT', + 'RETURN 1', + false +); +---- + +.Results +[opts="header"] +|=== +| value +| [1] +|=== + +Moreover, we can pass a `description` parameter as the 4th parameter, +which will be returned by the `call apoc.custom.list` and the `show functions`. \ No newline at end of file diff --git a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareProcedure.adoc b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareProcedure.adoc index 6840d35da4..7a0c7e6efe 100644 --- a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareProcedure.adoc +++ b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareProcedure.adoc @@ -1,3 +1,53 @@ +Here is a simple example: + +[source,cypher] +---- +CALL apoc.custom.declareProcedure('answerInteger() :: (row::INT)', 'RETURN 42 as answer') +---- + +This registers the statement as procedure `custom.answer` that you then can call. +[source,cypher] +---- +CALL custom.answerInteger +---- + +.Results +[opts="header"] +|=== +| answer +| 42 +|=== + +Or you can also write in this way: + +[source,cypher] +---- +CALL apoc.custom.declareProcedure('answer() :: (row::MAP)', 'RETURN 42 as answer') +---- + +In this case the result is wrapped in a stream of maps called `row`. Therefore, you can do: + +[source,cypher] +---- +CALL custom.answer() YIELD row +RETURN row.answer +---- + +.Results +[opts="header"] +|=== +| answer +| 42 +|=== + +which is equivalent to deprecated one: + +[source,cypher] +---- +CALL apoc.custom.asProcedure('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: [source,cypher] @@ -26,4 +76,15 @@ call custom.powers(4,3); | 4.0 | 16.0 | 64.0 -|=== \ No newline at end of file +|=== + + +Furthermore, we can pass as the 3rd parameter a string to specify the procedure mode (with default "WRITE"). +Can be: +- "READ" - if the procedure will only perform read operations against the graph +- "WRITE" - if it may perform both read and write operations against the graph +- "SCHEMA" - if it will perform operations against the schema +- "DBMS" - if it will perform system operations - i.e. not against the graph + +Moreover, we can pass a `description` parameter as the 4th parameter, +which will be returned by the `call apoc.custom.list` and the `show procedures`. \ No newline at end of file From e5a7e43fd49ee1b237d2c0878ca63b3e7a668bf7 Mon Sep 17 00:00:00 2001 From: Giuseppe Villani Date: Thu, 26 May 2022 09:10:56 +0200 Subject: [PATCH 2/3] small fixes --- .../cypher-execution/cypher-based-procedures-functions.adoc | 2 +- .../ROOT/partials/usage/apoc.custom.declareProcedure.adoc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/asciidoc/modules/ROOT/pages/cypher-execution/cypher-based-procedures-functions.adoc b/docs/asciidoc/modules/ROOT/pages/cypher-execution/cypher-based-procedures-functions.adoc index 733b87e9fd..3eb3566504 100644 --- a/docs/asciidoc/modules/ROOT/pages/cypher-execution/cypher-based-procedures-functions.adoc +++ b/docs/asciidoc/modules/ROOT/pages/cypher-execution/cypher-based-procedures-functions.adoc @@ -23,7 +23,7 @@ that is: Note that, for both procedures and functions, the `= defaultValue` are optionals. -The `type`s are what you would expect and see in outputs of `SHOW PROCEDURES`, `SHOW FUNCTIONS` or `apoc.help` just without the `?`. +The `type`s are what you would expect to see in outputs of `SHOW PROCEDURES`, `SHOW FUNCTIONS` or `apoc.help` just without the `?`. .Type Names * FLOAT, DOUBLE, INT, INTEGER, NUMBER, LONG diff --git a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareProcedure.adoc b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareProcedure.adoc index 7a0c7e6efe..19dffb7634 100644 --- a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareProcedure.adoc +++ b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareProcedure.adoc @@ -79,8 +79,8 @@ call custom.powers(4,3); |=== -Furthermore, we can pass as the 3rd parameter a string to specify the procedure mode (with default "WRITE"). -Can be: +Furthermore, we can pass as the 3rd parameter a string to specify the procedure mode (default "WRITE"). +It can be: - "READ" - if the procedure will only perform read operations against the graph - "WRITE" - if it may perform both read and write operations against the graph - "SCHEMA" - if it will perform operations against the schema From 13008acf006cff4a9b7f6e252b75118734e1e3c2 Mon Sep 17 00:00:00 2001 From: Giuseppe Villani Date: Thu, 9 Jun 2022 17:45:33 +0200 Subject: [PATCH 3/3] changes review --- .../cypher-based-procedures-functions.adoc | 85 +------------------ .../usage/apoc.custom.asFunction.adoc | 34 ++++++++ .../usage/apoc.custom.asProcedure.adoc | 51 +++++++++++ .../usage/apoc.custom.declareFunction.adoc | 2 +- .../usage/apoc.custom.declareProcedure.adoc | 2 +- 5 files changed, 89 insertions(+), 85 deletions(-) diff --git a/docs/asciidoc/modules/ROOT/pages/cypher-execution/cypher-based-procedures-functions.adoc b/docs/asciidoc/modules/ROOT/pages/cypher-execution/cypher-based-procedures-functions.adoc index 3eb3566504..3d4747e22d 100644 --- a/docs/asciidoc/modules/ROOT/pages/cypher-execution/cypher-based-procedures-functions.adoc +++ b/docs/asciidoc/modules/ROOT/pages/cypher-execution/cypher-based-procedures-functions.adoc @@ -23,9 +23,10 @@ that is: Note that, for both procedures and functions, the `= defaultValue` are optionals. -The `type`s are what you would expect to see in outputs of `SHOW PROCEDURES`, `SHOW FUNCTIONS` or `apoc.help` just without the `?`. .Type Names +The `typeParam` and `typeResult` in the signature parameter are what you would expect to see in outputs of `SHOW PROCEDURES`, `SHOW FUNCTIONS` or `CALL apoc.help('')`, just without the final `?`. +The following values are supported: * FLOAT, DOUBLE, INT, INTEGER, NUMBER, LONG * TEXT, STRING * BOOL, BOOLEAN @@ -133,85 +134,3 @@ please see the xref::overview/apoc.systemdb/apoc.systemdb.export.metadata.adoc[a ==== -== [DEPRECATED] Custom Procedures with `apoc.custom.asProcedure` - -Here is a simple example: - -[source,cypher] ----- -CALL apoc.custom.asProcedure('answer','RETURN 42 as answer') ----- - -This registers the statement as procedure `custom.answer` that you then can call. -As no information on a parameter and return types is given, it just returns a stream of columns of maps called `row`. - -[source,cypher] ----- -CALL custom.answer() YIELD row -RETURN row.answer ----- - -Given statement will be registered as a procedure, the results will be turned into a stream of records. - -.Parameters -[%autowidth,opts=header,cols="m,m,a"] -|=== -| name -| default -| description - -| name | none | dot-separated name, will be prefixed with `custom` -| statement | none | cypher statement to run, can use $parameters -| mode | read | execution mode of the procedure: read, write, or schema -| outputs | [["row","MAP"]] | List of pairs of name-type to be used as output columns, need to be in-order with the cypher statement, the default is a special case, that will collect all columns of the statement result into a map -| inputs | [["params","MAP","{}"]] | Pairs or triples of name-type-default, to be used as input parameters. The default just takes an optional map, otherwise they will become proper paramters in order -| description | "" | A general description about the business rules implemented into the procedure -|=== - -The type names can be the same as `apoc.custom.declare*` analogues. -The default values are parsed as JSON. - -.Find neighbours of a node by name -[source,cypher] ----- -CALL apoc.custom.asProcedure('neighbours', - 'MATCH (n:Person {name:$name})-->(nb) RETURN nb as neighbour','read', - [['neighbour','NODE']],[['name','STRING']], 'get neighbours of a person'); - -CALL custom.neighbours('Keanu Reeves') YIELD neighbour; ----- - - - -== [DEPRECATED] Custom Functions with `apoc.custom.asFunction` - -The same is possible as a function: - -[source,cypher] ----- -CALL apoc.custom.asFunction('answer','RETURN 42') ----- - -Given statement will be registered as a statement, the results into a single value. -If the given output type is a list, results will be collected into a list, otherwise the first row will be used. -The statement needs to return a single column, otherwise an error is thrown. - -.Parameters -[%autowidth,opts=header, cols="m,m,a"] -|=== -| name -| default -| description - -| name | none | dot-separated name, will be prefixed with `custom` -| statement | none | cypher statement to run, can use $parameters -| outputs | "LIST OF MAP" | Output type for single output, if the type is a list, then all rows will be collected, otherwise just the first row. Only single column results are allowed. -If your single row result is a list you can force a single row by setting the last parameter to `true` -| inputs | [["params","MAP","{}"]] | Pairs or triples of name-type-default, to be used as input parameters. The default just takes an optional map, otherwise they will become proper parameters in order -| singleRow | false | If set to true, the statement is treated as single row even with the list result type, then your statement has to return a list. -| description | "" | A general description about the business rules implemented into the function -|=== - -The type names are what you would expect and see in outputs of `dbms.procedures` or `apoc.help` just without the `?`. -The default values are parsed as JSON. - diff --git a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.asFunction.adoc b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.asFunction.adoc index bd5a0171b0..5353291ad8 100644 --- a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.asFunction.adoc +++ b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.asFunction.adoc @@ -1,3 +1,37 @@ +Please note that `apoc.custom.asFunction` and `apoc.custom.asProcedure` are deprecated in favor of `apoc.custom.declareFunction` and `apoc.custom.declareProcedure`. +xref::cypher-execution/cypher-based-procedures-functions.adoc[See here for more info]. + +This is the list of input parameters, `name` and `statement` are mandatory fields: + +.Parameters +[%autowidth,opts=header, cols="m,m,a"] +|=== +| name | default | description + +| name | none | dot-separated name, will be prefixed with `custom` +| statement | none | cypher statement to run, can use $parameters +| outputs | "LIST OF MAP" | Output type for single output, if the type is a list, then all rows will be collected, otherwise just the first row. Only single column results are allowed. +If your single row result is a list you can force a single row by setting the last parameter to `true` +| inputs | [["params","MAP","{}"]] | Pairs or triples of name-type-default, to be used as input parameters. The default just takes an optional map, otherwise they will become proper parameters in order +| singleRow | false | If set to true, the statement is treated as single row even with the list result type, then your statement has to return a list. +| description | "" | A general description about the business rules implemented into the function +|=== + +Given statement will be registered as a statement, the results into a single value. +If the given output type is a list, results will be collected into a list, otherwise the first row will be used. +The statement needs to return a single column, otherwise an error is thrown. + +The type names can be the same as `apoc.custom.declare*` analogues. + + +Here is a simple example: + +[source,cypher] +---- +CALL apoc.custom.asFunction('answer','RETURN 42') +---- + + We can create the function `custom.double`, that doubles the provided value, by running the following function: [source,cypher] diff --git a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.asProcedure.adoc b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.asProcedure.adoc index 3e9a1d50c9..ea771570bd 100644 --- a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.asProcedure.adoc +++ b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.asProcedure.adoc @@ -1,3 +1,54 @@ +Please note that `apoc.custom.asFunction` and `apoc.custom.asProcedure` are deprecated in favor of `apoc.custom.declareFunction` and `apoc.custom.declareProcedure`. +xref::cypher-execution/cypher-based-procedures-functions.adoc[See here for more info]. + +This is the list of input parameters, `name` and `statement` are mandatory fields: + +.Parameters +[%autowidth,opts=header,cols="m,m,a"] +|=== +| name | default | description + +| name | none | dot-separated name, will be prefixed with `custom` +| statement | none | cypher statement to run, can use $parameters +| mode | read | execution mode of the procedure: read, write, or schema +| outputs | [["row","MAP"]] | List of pairs of name-type to be used as output columns, need to be in-order with the cypher statement, the default is a special case, that will collect all columns of the statement result into a map +| inputs | [["params","MAP","{}"]] | Pairs or triples of name-type-default, to be used as input parameters. The default just takes an optional map, otherwise they will become proper paramters in order +| description | "" | A general description about the business rules implemented into the procedure +|=== + +Given statement will be registered as a procedure, the results will be turned into a stream of records. +The type names can be the same as `apoc.custom.declare*` analogues. + + +Here is a simple example: + +[source,cypher] +---- +CALL apoc.custom.asProcedure('answer','RETURN 42 as answer') +---- + +This registers the statement as procedure `custom.answer` that you then can call. +As no information on a parameter and return types is given, it just returns a stream of columns of maps called `row`. + +[source,cypher] +---- +CALL custom.answer() YIELD row +RETURN row.answer +---- + + + +.Find neighbours of a node by name +[source,cypher] +---- +CALL apoc.custom.asProcedure('neighbours', + 'MATCH (n:Person {name:$name})-->(nb) RETURN nb as neighbour','read', + [['neighbour','NODE']],[['name','STRING']], 'get neighbours of a person'); + +CALL custom.neighbours('Keanu Reeves') YIELD neighbour; +---- + + 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: [source,cypher] diff --git a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareFunction.adoc b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareFunction.adoc index 99338b61ee..7cbc947222 100644 --- a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareFunction.adoc +++ b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareFunction.adoc @@ -123,4 +123,4 @@ CALL apoc.custom.declareFunction('forceSingleFalse(input::ANY) :: LIST OF INT', |=== Moreover, we can pass a `description` parameter as the 4th parameter, -which will be returned by the `call apoc.custom.list` and the `show functions`. \ No newline at end of file +which will be returned by the `call apoc.custom.list` and `SHOW FUNCTIONS`. \ No newline at end of file diff --git a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareProcedure.adoc b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareProcedure.adoc index 19dffb7634..50e67f096c 100644 --- a/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareProcedure.adoc +++ b/docs/asciidoc/modules/ROOT/partials/usage/apoc.custom.declareProcedure.adoc @@ -87,4 +87,4 @@ It can be: - "DBMS" - if it will perform system operations - i.e. not against the graph Moreover, we can pass a `description` parameter as the 4th parameter, -which will be returned by the `call apoc.custom.list` and the `show procedures`. \ No newline at end of file +which will be returned by the `call apoc.custom.list` and `SHOW PROCEDURES`. \ No newline at end of file