Skip to content

Commit 8e8ee39

Browse files
JoelBergstrandrsill-neo4jNataliaIvakina
authored
Clarified naming rules for user defined callables and added list for reserved and deprecated namespaces (#310)
* Clarified naming rules for user defined callables and added list for reserved and deprecated namespaces * Apply suggestions from code review Co-authored-by: Richard Sill <156673635+rsill-neo4j@users.noreply.github.com> * Updated deprecating root for procedures * Update modules/ROOT/pages/extending-neo4j/procedures.adoc * Apply suggestions from code review --------- Co-authored-by: Richard Sill <156673635+rsill-neo4j@users.noreply.github.com> Co-authored-by: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com>
1 parent 279219f commit 8e8ee39

File tree

3 files changed

+148
-1
lines changed

3 files changed

+148
-1
lines changed

‎modules/ROOT/pages/extending-neo4j/aggregation-functions.adoc‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,13 @@ An aggregator class contains one method annotated with `@UserAggregationUpdate`
3232
The method annotated with `@UserAggregationUpdate` will be called multiple times and enables the class to aggregate data.
3333
When the aggregation is done, the method annotated with `@UserAggregationResult` will be called once and the result of the aggregation will be returned.
3434

35+
Particular things to note:
36+
37+
* All functions are annotated with `@UserAggregationFunction`.
38+
* The aggregation function name must be namespaced and is not allowed in reserved namespaces.
39+
* 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.
40+
41+
3542
See xref:extending-neo4j/values-and-types.adoc[] for details on values and types.
3643

3744
For more details, see the Neo4j Javadocs for link:{org-neo4j-procedure-UserAggregationFunction}[`org.neo4j.procedure.UserAggregationFunction`^].
@@ -132,3 +139,57 @@ public class LongestStringTest
132139
}
133140
----
134141

142+
[[reserved-and-deprecated-namespaces]]
143+
== Reserved and deprecated function namespaces
144+
145+
Note that deprecated function namespaces will be moved to reserved in the next major Cypher version.
146+
For more information about Neo4j and Cypher versioning, see link:https://neo4j.com/docs/operations-manual/current/introduction/#_cypher_versions[Operations manual -> Introduction].
147+
[[reserved-and-deprecated-function-namespaces]]
148+
.Overview of reserved and deprecated function namespaces and names
149+
[options="header", cols="m,m"]
150+
|===
151+
| Reserved | Deprecated in Cypher 25 since Neo4j 2025.11
152+
| * | abac.*
153+
| date | aura.*
154+
| date.realtime | builtin.*
155+
| date.statement | cdc.*
156+
| date.transaction | coll.*
157+
| date.truncate | date.*
158+
| datetime | datetime.*
159+
| datetime.fromepoch | db.*
160+
| datetime.fromepochmillis | dbms.*
161+
| datetime.realtime | duration.*
162+
| datetime.statement | graph.*
163+
| datetime.transaction | internal.*
164+
| datetime.truncate | localdatetime.*
165+
| db.nameFromElementId | localtime.*
166+
| duration | math.*
167+
| duration.between | plugin.*
168+
| duration.inDays | point.*
169+
| duration.inMonths | stored.*
170+
| duration.inSeconds | string.*
171+
| graph.byElementId | time.*
172+
| graph.byName | tx.*
173+
| graph.names | unsupported.*
174+
| graph.propertiesByName | vector.*
175+
| localdatetime |
176+
| localdatetime.realtime |
177+
| localdatetime.statement |
178+
| localdatetime.transaction |
179+
| localdatetime.truncate |
180+
| localtime |
181+
| localtime.realtime |
182+
| localtime.statement |
183+
| localtime.transaction |
184+
| localtime.truncate |
185+
| point.distance |
186+
| point.withinBBox |
187+
| time |
188+
| time.realtime |
189+
| time.statement |
190+
| time.transaction |
191+
| time.truncate |
192+
| vector.similarity.cosine |
193+
| vector.similarity.euclidean |
194+
|===
195+

‎modules/ROOT/pages/extending-neo4j/functions.adoc‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,12 @@ RETURN org.neo4j.examples.join(collect(p.names))
3030
User-defined functions are created similarly to how procedures are created.
3131
But unlike procedures, they are annotated with `@UserFunction` and return a single value instead of a stream of values.
3232

33+
Particular things to note:
34+
35+
* All functions are annotated with `@UserFunction`.
36+
* The function name must be namespaced and is not allowed in reserved namespaces.
37+
* If a function is registered with the same name as a built-in function in a deprecated namespace, the built-in function is shadowed.
38+
3339
See xref:extending-neo4j/values-and-types.adoc[] for details on values and types.
3440

3541
For more details, see the link:{org-neo4j-procedure-UserFunction}[Neo4j Javadocs for `org.neo4j.procedure.UserFunction`^].
@@ -120,3 +126,56 @@ public class JoinTest {
120126
}
121127
----
122128

129+
[[reserved-and-deprecated-namespaces]]
130+
== Reserved and deprecated function namespaces
131+
132+
Note that deprecated function namespaces will be moved to reserved in the next major Cypher version.
133+
For more information about Neo4j and Cypher versioning, see link:https://neo4j.com/docs/operations-manual/current/introduction/#_cypher_versions[Operations manual -> Introduction].
134+
[[reserved-and-deprecated-function-namespaces]]
135+
.Overview of reserved and deprecated function namespaces and names
136+
[options="header", cols="m,m"]
137+
|===
138+
| Reserved | Deprecated in Cypher 25 since Neo4j 2025.11
139+
| * | abac.*
140+
| date | aura.*
141+
| date.realtime | builtin.*
142+
| date.statement | cdc.*
143+
| date.transaction | coll.*
144+
| date.truncate | date.*
145+
| datetime | datetime.*
146+
| datetime.fromepoch | db.*
147+
| datetime.fromepochmillis | dbms.*
148+
| datetime.realtime | duration.*
149+
| datetime.statement | graph.*
150+
| datetime.transaction | internal.*
151+
| datetime.truncate | localdatetime.*
152+
| db.nameFromElementId | localtime.*
153+
| duration | math.*
154+
| duration.between | plugin.*
155+
| duration.inDays | point.*
156+
| duration.inMonths | stored.*
157+
| duration.inSeconds | string.*
158+
| graph.byElementId | time.*
159+
| graph.byName | tx.*
160+
| graph.names | unsupported.*
161+
| graph.propertiesByName | vector.*
162+
| localdatetime |
163+
| localdatetime.realtime |
164+
| localdatetime.statement |
165+
| localdatetime.transaction |
166+
| localdatetime.truncate |
167+
| localtime |
168+
| localtime.realtime |
169+
| localtime.statement |
170+
| localtime.transaction |
171+
| localtime.truncate |
172+
| point.distance |
173+
| point.withinBBox |
174+
| time |
175+
| time.realtime |
176+
| time.statement |
177+
| time.transaction |
178+
| time.truncate |
179+
| vector.similarity.cosine |
180+
| vector.similarity.euclidean |
181+
|===

‎modules/ROOT/pages/extending-neo4j/procedures.adoc‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,8 @@ Particular things to note:
143143
* The procedure annotation can take three optional arguments: `name`, `mode`, and `eager`.
144144
** `name` is used to specify a different name for the procedure than the default generated, which is `class.path.nameOfMethod`.
145145
If `mode` is specified, `name` must be specified as well.
146+
** `name` is not allowed in a reserved namespace, and having a `name` without a namespace is deprecated behavior.
147+
** If a procedure is registered with the same name as a built-in procedure in a deprecated namespace, the built-in procedure is shadowed.
146148
** `mode` is used to declare the types of interactions that the procedure performs.
147149
A procedure fails if it attempts to execute database operations that violate its mode.
148150
The default `mode` is `READ`.
@@ -163,7 +165,7 @@ Particular things to note:
163165
MATCH (n)
164166
WHERE n.key = 'value'
165167
WITH n
166-
CALL deleteNeighbours(n, 'FOLLOWS')
168+
CALL example.deleteNeighbours(n, 'FOLLOWS')
167169
----
168170
This query can delete some of the nodes that are matched by the Cypher query, and the `n.key` lookup will fail.
169171
Marking this procedure as `eager` prevents this from causing an error in Cypher code.
@@ -273,3 +275,28 @@ public class MyProcedures {
273275
}
274276
275277
----
278+
279+
[[reserved-and-deprecated-namespaces]]
280+
== Reserved and deprecated procedure namespaces
281+
282+
Note that deprecated procedure namespaces will be moved to reserved in the next major Cypher version.
283+
For more information about Neo4j and Cypher versioning, see link:https://neo4j.com/docs/operations-manual/current/introduction/#_cypher_versions[Operations manual -> Introduction].
284+
[[reserved-and-deprecated-procedure-namespaces]]
285+
.Overview of reserved and deprecated procedure namespaces
286+
[options="header", cols="m,m"]
287+
|===
288+
| Reserved | Deprecated in Cypher 25 since Neo4j 2025.11
289+
| cdc.* | *
290+
| date.* | abac.*
291+
| datetime.* | aura.*
292+
| db.* | builtin.*
293+
| dbms.* | coll.*
294+
| duration.* | math.*
295+
| graph.* | plugin.*
296+
| internal.* | point.*
297+
| localdatetime.* | stored.*
298+
| localtime.* | string.*
299+
| time.* | vector.*
300+
| tx.* |
301+
| unsupported.* |
302+
|===

0 commit comments

Comments
 (0)