org.neo4j.procedure

Annotation Type UserFunction

@Target(value=METHOD)
 @Retention(value=RUNTIME)
public @interface UserFunction

Declares a method as a Function, meaning the method can be called from the cypher query language.

Functions accept input, use that input to perform work, and then return a value. The work performed usually involves one or more resources, such as a GraphDatabaseService. Functions are read-only, i.e can't update neither the graph nor update schema.

Input declaration

A function can accept input arguments, which is defined in the arguments to the annotated method. Each method argument must be a valid Function input type, and each must be annotated with the Name annotation, declaring the input name.

Valid input types are as follows:

• String
• Long or long
• Double or double
• Number
• Boolean or boolean
• Node
• Relationship
• Path
• Map with key String and value of any type in this list, including Map
• List with element type of any type in this list, including List
• Object, meaning any valid input types

Output declaration

A function must always return a single value.

Valid return types are as follows:

• String
• Long or long
• Double or double
• Number
• Boolean or boolean
• Node
• Relationship
• Path
• Map with key String and value of any type in this list, including Map
• List of elements of any valid field type, including List
• Object, meaning any of the valid field types

Resource declarations

The function 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 function class, and annotating them with the Context annotation. Fields declared this way are automatically injected with the requested resource. This is how functions gain access to APIs to do work with.

All fields in the class containing the function 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

Lifecycle and state

The class that declares your function method may be re-instantiated before each call. Because of this, no regular state can be stored in the fields of the function.

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

Optional Elements

Modifier and Type	Optional Element and Description
String[]	allowed Specifies role names such that a user that is assigned to any of these roles is allowed to execute this function, regardless of any other permissions that the user has or doesn't have.
String	deprecatedBy When deprecating a function it is useful to indicate a possible replacement procedure that clients might show in warnings
String	name Synonym for value()
String	value The namespace and name for the function, as a period-separated string.

Element Detail

value

public abstract String value

The namespace and name for the function, as a period-separated string. For instance myfunctions.myfunction. 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

public abstract String name

Synonym for value()

Default:

""

deprecatedBy

public abstract String deprecatedBy

When deprecating a function it is useful to indicate a possible replacement procedure that clients might show in warnings

Default:

""

allowed

public abstract String[] allowed

Specifies role names such that a user that is assigned to any of these roles is allowed to execute this function, regardless of any other permissions that the user has or doesn't have. The use-case for this attribute is to allow users with no or little privileges to access the parts of the database that the annotated function exposes.

Returns:

an array of role names whose users are allowed to execute this function.

Default:

{}