From 106ab77491f01dd61b05843ae840a197011d30a1 Mon Sep 17 00:00:00 2001 From: Joel Bergstrand Date: Wed, 22 Oct 2025 10:59:38 +0200 Subject: [PATCH 1/4] Clarified naming rules for user defined callables and added list for reserved and deprecated namespaces --- .../aggregation-functions.adoc | 58 +++++++++++++++++++ .../ROOT/pages/extending-neo4j/functions.adoc | 38 ++++++++++++ .../pages/extending-neo4j/procedures.adoc | 54 ++++++++++++++++- 3 files changed, 149 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc b/modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc index c431189..412348a 100644 --- a/modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc +++ b/modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc @@ -32,6 +32,13 @@ An aggregator class contains one method annotated with `@UserAggregationUpdate` The method annotated with `@UserAggregationUpdate` will be called multiple times and enables the class to aggregate data. When the aggregation is done, the method annotated with `@UserAggregationResult` will be called once and the result of the aggregation will be returned. +Particular things to note: + +* All functions are annotated with `@UserAggregationFunction`. +* The aggregation function name is required to be namespaced and is not allowed in one of the reserved namespaces. +* If a user defined aggregation function is registered with the same name as a built-in function in a deprecated namespace the built-in function will be shadowed. + + See xref:extending-neo4j/values-and-types.adoc[] for details on values and types. For more details, see the Neo4j Javadocs for link:{org-neo4j-procedure-UserAggregationFunction}[`org.neo4j.procedure.UserAggregationFunction`^]. @@ -132,3 +139,54 @@ public class LongestStringTest } ---- +[[reserved-and-deprecated-namespaces]] +== Reserved and deprecated function namespaces + +[[reserved-and-deprecated-function-namespaces]] +.Overview of reserved and deprecated function namespaces and names +[options="header", cols="m,m"] +|=== +| Reserved | Deprecated +| date |abac.* +| date.realtime |aura.* +| date.statement |builtin.* +| date.transaction |cdc.* +| date.truncate |coll.* +| datetime |date.* +| datetime.fromepoch |datetime.* +| datetime.fromepochmillis |db.* +| datetime.realtime |dbms.* +| datetime.statement |duration.* +| datetime.transaction |graph.* +| datetime.truncate |internal.* +| db.nameFromElementId |localdatetime.* +| duration |localtime.* +| duration.between |math.* +| duration.inDays |plugin.* +| duration.inMonths |point.* +| duration.inSeconds |stored.* +| graph.byElementId |string.* +| graph.byName |time.* +| graph.names |tx.* +| graph.propertiesByName |unsupported.* +| localdatetime |vector.* +| localdatetime.realtime | +| localdatetime.statement | +| localdatetime.transaction | +| localdatetime.truncate | +| localtime | +| localtime.realtime | +| localtime.statement | +| localtime.transaction | +| localtime.truncate | +| point.distance | +| point.withinBBox | +| time | +| time.realtime | +| time.statement | +| time.transaction | +| time.truncate | +| vector.similarity.cosine | +| vector.similarity.euclidean | +|=== + diff --git a/modules/ROOT/pages/extending-neo4j/functions.adoc b/modules/ROOT/pages/extending-neo4j/functions.adoc index 147957f..19ccd9e 100644 --- a/modules/ROOT/pages/extending-neo4j/functions.adoc +++ b/modules/ROOT/pages/extending-neo4j/functions.adoc @@ -30,6 +30,12 @@ RETURN org.neo4j.examples.join(collect(p.names)) User-defined functions are created similarly to how procedures are created. But unlike procedures, they are annotated with `@UserFunction` and return a single value instead of a stream of values. +Particular things to note: + +* All functions are annotated with `@UserFunction`. +* The function name is required to be namespaced and is not allowed in one of the reserved namespaces. +* If a function is registered with the same name as a built-in function in a deprecated namespace the built-in function will be shadowed. + See xref:extending-neo4j/values-and-types.adoc[] for details on values and types. For more details, see the link:{org-neo4j-procedure-UserFunction}[Neo4j Javadocs for `org.neo4j.procedure.UserFunction`^]. @@ -120,3 +126,35 @@ public class JoinTest { } ---- +[[reserved-and-deprecated-namespaces]] +== Reserved and deprecated function namespaces + +[[reserved-and-deprecated-function-namespaces]] +.Overview of reserved and deprecated function namespaces and names +[options="header", cols="m,m"] +|=== +| Reserved | Deprecated +| cdc.* | abac.* +| date.* | aura.* +| datetime.* | builtin.* +| db.* | coll.* +| dbms.* | math.* +| duration.* | plugin.* +| graph.* | point.* +| internal.* | stored.* +| localdatetime.* | string.* +| localtime.* | vector.* +| time.* | +| tx.* | +| unsupported.* | +|=== + + + + + + + + + + diff --git a/modules/ROOT/pages/extending-neo4j/procedures.adoc b/modules/ROOT/pages/extending-neo4j/procedures.adoc index 2d61214..c57be31 100644 --- a/modules/ROOT/pages/extending-neo4j/procedures.adoc +++ b/modules/ROOT/pages/extending-neo4j/procedures.adoc @@ -143,6 +143,8 @@ Particular things to note: * The procedure annotation can take three optional arguments: `name`, `mode`, and `eager`. ** `name` is used to specify a different name for the procedure than the default generated, which is `class.path.nameOfMethod`. If `mode` is specified, `name` must be specified as well. +** `name` is required to be namespaced and is not allowed in one of the reserved namespaces. +** If a procedure is registered with the same name as a built-in procedure in a deprecated namespace the built-in procedure will be shadowed. ** `mode` is used to declare the types of interactions that the procedure performs. A procedure fails if it attempts to execute database operations that violate its mode. The default `mode` is `READ`. @@ -163,7 +165,7 @@ Particular things to note: MATCH (n) WHERE n.key = 'value' WITH n -CALL deleteNeighbours(n, 'FOLLOWS') +CALL example.deleteNeighbours(n, 'FOLLOWS') ---- This query can delete some of the nodes that are matched by the Cypher query, and the `n.key` lookup will fail. Marking this procedure as `eager` prevents this from causing an error in Cypher code. @@ -273,3 +275,53 @@ public class MyProcedures { } ---- +[[reserved-and-deprecated-namespaces]] +== Reserved and deprecated function namespaces + +[[reserved-and-deprecated-function-namespaces]] +.Overview of reserved and deprecated function namespaces and names +[options="header", cols="m,m"] +|=== +| Reserved | Deprecated +| date |abac.* +| date.realtime |aura.* +| date.statement |builtin.* +| date.transaction |cdc.* +| date.truncate |coll.* +| datetime |date.* +| datetime.fromepoch |datetime.* +| datetime.fromepochmillis |db.* +| datetime.realtime |dbms.* +| datetime.statement |duration.* +| datetime.transaction |graph.* +| datetime.truncate |internal.* +| db.nameFromElementId |localdatetime.* +| duration |localtime.* +| duration.between |math.* +| duration.inDays |plugin.* +| duration.inMonths |point.* +| duration.inSeconds |stored.* +| graph.byElementId |string.* +| graph.byName |time.* +| graph.names |tx.* +| graph.propertiesByName |unsupported.* +| localdatetime |vector.* +| localdatetime.realtime | +| localdatetime.statement | +| localdatetime.transaction | +| localdatetime.truncate | +| localtime | +| localtime.realtime | +| localtime.statement | +| localtime.transaction | +| localtime.truncate | +| point.distance | +| point.withinBBox | +| time | +| time.realtime | +| time.statement | +| time.transaction | +| time.truncate | +| vector.similarity.cosine | +| vector.similarity.euclidean | +|=== From 90b2192310fc5695b7c871850748b4945c18333d Mon Sep 17 00:00:00 2001 From: JoelBergstrand Date: Wed, 22 Oct 2025 16:18:24 +0200 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Richard Sill <156673635+rsill-neo4j@users.noreply.github.com> --- modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc | 4 ++-- modules/ROOT/pages/extending-neo4j/functions.adoc | 4 ++-- modules/ROOT/pages/extending-neo4j/procedures.adoc | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc b/modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc index 412348a..99a33e9 100644 --- a/modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc +++ b/modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc @@ -35,8 +35,8 @@ When the aggregation is done, the method annotated with `@UserAggregationResult` Particular things to note: * All functions are annotated with `@UserAggregationFunction`. -* The aggregation function name is required to be namespaced and is not allowed in one of the reserved namespaces. -* If a user defined aggregation function is registered with the same name as a built-in function in a deprecated namespace the built-in function will be shadowed. +* The aggregation function name must be namespaced and is not allowed in reserved namespaces. +* If a user-defined aggregation function is registered with the same name as a built-in function in a deprecated namespace, the built-in function is shadowed. See xref:extending-neo4j/values-and-types.adoc[] for details on values and types. diff --git a/modules/ROOT/pages/extending-neo4j/functions.adoc b/modules/ROOT/pages/extending-neo4j/functions.adoc index 19ccd9e..742a449 100644 --- a/modules/ROOT/pages/extending-neo4j/functions.adoc +++ b/modules/ROOT/pages/extending-neo4j/functions.adoc @@ -33,8 +33,8 @@ But unlike procedures, they are annotated with `@UserFunction` and return a sing Particular things to note: * All functions are annotated with `@UserFunction`. -* The function name is required to be namespaced and is not allowed in one of the reserved namespaces. -* If a function is registered with the same name as a built-in function in a deprecated namespace the built-in function will be shadowed. +* The function name must be namespaced and is not allowed in reserved namespaces. +* If a function is registered with the same name as a built-in function in a deprecated namespace, the built-in function is shadowed. See xref:extending-neo4j/values-and-types.adoc[] for details on values and types. diff --git a/modules/ROOT/pages/extending-neo4j/procedures.adoc b/modules/ROOT/pages/extending-neo4j/procedures.adoc index c57be31..859a09d 100644 --- a/modules/ROOT/pages/extending-neo4j/procedures.adoc +++ b/modules/ROOT/pages/extending-neo4j/procedures.adoc @@ -143,8 +143,8 @@ Particular things to note: * The procedure annotation can take three optional arguments: `name`, `mode`, and `eager`. ** `name` is used to specify a different name for the procedure than the default generated, which is `class.path.nameOfMethod`. If `mode` is specified, `name` must be specified as well. -** `name` is required to be namespaced and is not allowed in one of the reserved namespaces. -** If a procedure is registered with the same name as a built-in procedure in a deprecated namespace the built-in procedure will be shadowed. +** `name` must be namespaced and is not allowed in reserved namespaces. +** If a procedure is registered with the same name as a built-in procedure in a deprecated namespace, the built-in procedure is shadowed. ** `mode` is used to declare the types of interactions that the procedure performs. A procedure fails if it attempts to execute database operations that violate its mode. The default `mode` is `READ`. From c9b79990a9a59fed4cf1c3a343e73190530e16d9 Mon Sep 17 00:00:00 2001 From: Joel Bergstrand Date: Thu, 23 Oct 2025 11:09:41 +0200 Subject: [PATCH 3/4] Updated deprecating root for procedures --- .../aggregation-functions.adoc | 49 ++++++------- .../ROOT/pages/extending-neo4j/functions.adoc | 69 ++++++++++++------- .../pages/extending-neo4j/procedures.adoc | 67 ++++++------------ 3 files changed, 89 insertions(+), 96 deletions(-) diff --git a/modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc b/modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc index 99a33e9..518a6dd 100644 --- a/modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc +++ b/modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc @@ -146,30 +146,31 @@ public class LongestStringTest .Overview of reserved and deprecated function namespaces and names [options="header", cols="m,m"] |=== -| Reserved | Deprecated -| date |abac.* -| date.realtime |aura.* -| date.statement |builtin.* -| date.transaction |cdc.* -| date.truncate |coll.* -| datetime |date.* -| datetime.fromepoch |datetime.* -| datetime.fromepochmillis |db.* -| datetime.realtime |dbms.* -| datetime.statement |duration.* -| datetime.transaction |graph.* -| datetime.truncate |internal.* -| db.nameFromElementId |localdatetime.* -| duration |localtime.* -| duration.between |math.* -| duration.inDays |plugin.* -| duration.inMonths |point.* -| duration.inSeconds |stored.* -| graph.byElementId |string.* -| graph.byName |time.* -| graph.names |tx.* -| graph.propertiesByName |unsupported.* -| localdatetime |vector.* +| Reserved | Deprecated since Neo4j 2025.11 +| * | abac.* +| date | aura.* +| date.realtime | builtin.* +| date.statement | cdc.* +| date.transaction | coll.* +| date.truncate | date.* +| datetime | datetime.* +| datetime.fromepoch | db.* +| datetime.fromepochmillis | dbms.* +| datetime.realtime | duration.* +| datetime.statement | graph.* +| datetime.transaction | internal.* +| datetime.truncate | localdatetime.* +| db.nameFromElementId | localtime.* +| duration | math.* +| duration.between | plugin.* +| duration.inDays | point.* +| duration.inMonths | stored.* +| duration.inSeconds | string.* +| graph.byElementId | time.* +| graph.byName | tx.* +| graph.names | unsupported.* +| graph.propertiesByName | vector.* +| localdatetime | | localdatetime.realtime | | localdatetime.statement | | localdatetime.transaction | diff --git a/modules/ROOT/pages/extending-neo4j/functions.adoc b/modules/ROOT/pages/extending-neo4j/functions.adoc index 742a449..4eb665c 100644 --- a/modules/ROOT/pages/extending-neo4j/functions.adoc +++ b/modules/ROOT/pages/extending-neo4j/functions.adoc @@ -133,28 +133,47 @@ public class JoinTest { .Overview of reserved and deprecated function namespaces and names [options="header", cols="m,m"] |=== -| Reserved | Deprecated -| cdc.* | abac.* -| date.* | aura.* -| datetime.* | builtin.* -| db.* | coll.* -| dbms.* | math.* -| duration.* | plugin.* -| graph.* | point.* -| internal.* | stored.* -| localdatetime.* | string.* -| localtime.* | vector.* -| time.* | -| tx.* | -| unsupported.* | -|=== - - - - - - - - - - +| Reserved | Deprecated since Neo4j 2025.11 +| * | abac.* +| date | aura.* +| date.realtime | builtin.* +| date.statement | cdc.* +| date.transaction | coll.* +| date.truncate | date.* +| datetime | datetime.* +| datetime.fromepoch | db.* +| datetime.fromepochmillis | dbms.* +| datetime.realtime | duration.* +| datetime.statement | graph.* +| datetime.transaction | internal.* +| datetime.truncate | localdatetime.* +| db.nameFromElementId | localtime.* +| duration | math.* +| duration.between | plugin.* +| duration.inDays | point.* +| duration.inMonths | stored.* +| duration.inSeconds | string.* +| graph.byElementId | time.* +| graph.byName | tx.* +| graph.names | unsupported.* +| graph.propertiesByName | vector.* +| localdatetime | +| localdatetime.realtime | +| localdatetime.statement | +| localdatetime.transaction | +| localdatetime.truncate | +| localtime | +| localtime.realtime | +| localtime.statement | +| localtime.transaction | +| localtime.truncate | +| point.distance | +| point.withinBBox | +| time | +| time.realtime | +| time.statement | +| time.transaction | +| time.truncate | +| vector.similarity.cosine | +| vector.similarity.euclidean | +|=== \ No newline at end of file diff --git a/modules/ROOT/pages/extending-neo4j/procedures.adoc b/modules/ROOT/pages/extending-neo4j/procedures.adoc index 859a09d..4a55ec6 100644 --- a/modules/ROOT/pages/extending-neo4j/procedures.adoc +++ b/modules/ROOT/pages/extending-neo4j/procedures.adoc @@ -143,8 +143,8 @@ Particular things to note: * The procedure annotation can take three optional arguments: `name`, `mode`, and `eager`. ** `name` is used to specify a different name for the procedure than the default generated, which is `class.path.nameOfMethod`. If `mode` is specified, `name` must be specified as well. -** `name` must be namespaced and is not allowed in reserved namespaces. -** If a procedure is registered with the same name as a built-in procedure in a deprecated namespace, the built-in procedure is shadowed. +** `name` is not allowed in a reserved namespace, and having a `name` without a namespace is deprecated behavior. +** If a procedure is registered with the same name as a built-in procedure in a deprecated namespace the built-in procedure will be shadowed. ** `mode` is used to declare the types of interactions that the procedure performs. A procedure fails if it attempts to execute database operations that violate its mode. The default `mode` is `READ`. @@ -275,53 +275,26 @@ public class MyProcedures { } ---- + [[reserved-and-deprecated-namespaces]] -== Reserved and deprecated function namespaces +== Reserved and deprecated procedure namespaces -[[reserved-and-deprecated-function-namespaces]] -.Overview of reserved and deprecated function namespaces and names +[[reserved-and-deprecated-procedure-namespaces]] +.Overview of reserved and deprecated procedure namespaces [options="header", cols="m,m"] |=== -| Reserved | Deprecated -| date |abac.* -| date.realtime |aura.* -| date.statement |builtin.* -| date.transaction |cdc.* -| date.truncate |coll.* -| datetime |date.* -| datetime.fromepoch |datetime.* -| datetime.fromepochmillis |db.* -| datetime.realtime |dbms.* -| datetime.statement |duration.* -| datetime.transaction |graph.* -| datetime.truncate |internal.* -| db.nameFromElementId |localdatetime.* -| duration |localtime.* -| duration.between |math.* -| duration.inDays |plugin.* -| duration.inMonths |point.* -| duration.inSeconds |stored.* -| graph.byElementId |string.* -| graph.byName |time.* -| graph.names |tx.* -| graph.propertiesByName |unsupported.* -| localdatetime |vector.* -| localdatetime.realtime | -| localdatetime.statement | -| localdatetime.transaction | -| localdatetime.truncate | -| localtime | -| localtime.realtime | -| localtime.statement | -| localtime.transaction | -| localtime.truncate | -| point.distance | -| point.withinBBox | -| time | -| time.realtime | -| time.statement | -| time.transaction | -| time.truncate | -| vector.similarity.cosine | -| vector.similarity.euclidean | +| Reserved | Deprecated since Neo4j 2025.11 +| cdc.* | * +| date.* | abac.* +| datetime.* | aura.* +| db.* | builtin.* +| dbms.* | coll.* +| duration.* | math.* +| graph.* | plugin.* +| internal.* | point.* +| localdatetime.* | stored.* +| localtime.* | string.* +| time.* | vector.* +| tx.* | +| unsupported.* | |=== From 1d92880993531c7e39d4fbff70684580ce9a71cb Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Fri, 24 Oct 2025 10:23:30 +0200 Subject: [PATCH 4/4] Update modules/ROOT/pages/extending-neo4j/procedures.adoc --- modules/ROOT/pages/extending-neo4j/procedures.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/extending-neo4j/procedures.adoc b/modules/ROOT/pages/extending-neo4j/procedures.adoc index 4a55ec6..908d15f 100644 --- a/modules/ROOT/pages/extending-neo4j/procedures.adoc +++ b/modules/ROOT/pages/extending-neo4j/procedures.adoc @@ -144,7 +144,7 @@ Particular things to note: ** `name` is used to specify a different name for the procedure than the default generated, which is `class.path.nameOfMethod`. If `mode` is specified, `name` must be specified as well. ** `name` is not allowed in a reserved namespace, and having a `name` without a namespace is deprecated behavior. -** If a procedure is registered with the same name as a built-in procedure in a deprecated namespace the built-in procedure will be shadowed. +** If a procedure is registered with the same name as a built-in procedure in a deprecated namespace, the built-in procedure is shadowed. ** `mode` is used to declare the types of interactions that the procedure performs. A procedure fails if it attempts to execute database operations that violate its mode. The default `mode` is `READ`.