Annotation Interface Procedure
Procedures accept input, use that input to perform work, and then return a
Stream
of Records
. The work performed usually
involves one or more resources, such as a GraphDatabaseService
.
A procedure is associated with one of the following modes READ allows only reading the graph (default mode) WRITE allows reading and writing the graph SCHEMA allows reading the graphs and performing schema operations DBMS allows managing the database (i.e. change password)
Input declaration
A procedure can accept input arguments, which is defined in the arguments to the annotated method. Each method argument must be a valid Procedure input type, and each must be annotated with theName
annotation, declaring the input name.
Valid input types are as follows:
String
Long
orlong
Double
ordouble
Number
Boolean
orboolean
Node
Relationship
Path
Map
with keyString
and value of any type in this list, includingMap
List
with element type of any type in this list, includingList
Object
, meaning any of the valid input types above
Output declaration
A procedure must always return aStream
of Records
, or nothing.
The record is defined per procedure, as a class with only public, non-final fields.
The types, order and names of the fields in this class define the format of the returned records.
Valid field types are as follows:
String
Long
orlong
Double
ordouble
Number
Boolean
orboolean
Node
Relationship
Path
Map
with keyString
and value of any type in this list, includingMap
List
of elements of any valid field type, includingList
Object
, meaning any of the valid field types above
Resource declarations
The procedure method itself can contain arbitrary Java code - but in order to work with the underlying graph, it must have access to the graph API. This is done by declaring fields in the procedure class, and annotating them with theContext
annotation. Fields declared this way are automatically injected with the
requested resource. This is how procedures gain access to APIs to do work with.
All fields in the class containing the procedure declaration must either be static; or it must be public, non-final
and annotated with Context
.
Resources supported by default are as follows:
GraphDatabaseService
Log
TerminationGuard
Lifecycle and state
The class that declares your procedure method may be re-instantiated before each call. Because of this, no regular state can be stored in the fields of the procedure.If you want to maintain state between invocations to your procedure, simply use a static field. Note that procedures may be called concurrently, meaning you need to take care to ensure the state you store in static fields can be safely accessed by multiple callers simultaneously.
-
Optional Element Summary
Modifier and TypeOptional ElementDescriptionWhen deprecating a procedure it is useful to indicate a possible replacement procedure that clients might show in warnings.boolean
Cypher normally streams data lazily between operations, but for read-write queries this can cause side effects that can only be solved usingEager
operators between the read and write components.A procedure is associated with one of the following modes READ allows only reading the graph (default mode) WRITE allows reading and writing the graph SCHEMA allows reading the graphs and performing schema operations DBMS allows managing the database (i.e.Synonym forvalue()
The namespace and name for the procedure, as a period-separated string.
-
Element Details
-
value
String valueThe namespace and name for the procedure, as a period-separated string. For instancemyprocedures.myprocedure
. If this is left empty, the name defaults to the package name of the class the procedure is declared in, combined with the method name. Notably, the class name is omitted.- Returns:
- the namespace and procedure name.
- Default:
- ""
-
name
String nameSynonym forvalue()
- Returns:
- the namespace and procedure name.
- Default:
- ""
-
mode
Mode modeA procedure is associated with one of the following modes READ allows only reading the graph (default mode) WRITE allows reading and writing the graph SCHEMA allows reading the graphs and performing schema operations DBMS allows managing the database (i.e. change password)- Returns:
- the associated mode.
- Default:
- DEFAULT
-
eager
boolean eagerCypher normally streams data lazily between operations, but for read-write queries this can cause side effects that can only be solved usingEager
operators between the read and write components. Cypher can plan this for you for pure Cypher queries, but when you include aWRITE
procedure into the query the planner will not know enough about the internals of the procedure to figure this out. If the procedure can perform updates (like deletes) that might negatively impact preceding reads in the Cypher query, then set this annotation attribute totrue
, so that all reads will be completed before calling the procedure. Note that this does not prevent the procedure from negatively interacting with itself, and developers still need to catch and deal with relevant exceptions themselves.- Default:
- false
-
deprecatedBy
String deprecatedByWhen deprecating a procedure it is useful to indicate a possible replacement procedure that clients might show in warnings.- Returns:
- a string representation of the replacement procedure.
- Default:
- ""
-