Package org.neo4j.cypherdsl.core

Class Cypher

  • @API(status=EXPERIMENTAL,
     since="1.0")
public final class Cypher
extends java.lang.Object
    The main entry point into the Cypher DSL. The Cypher Builder API is intended for framework usage to produce Cypher statements required for database operations.
    Since:
    1.0
    Author:
    Michael J. Simons, Gerrit Meier, Andreas Berger

    • Method Detail

      • node

        @NotNull
@Contract(pure=true)
public static @NotNull Node node​(java.lang.String primaryLabel,
                                 java.lang.String... additionalLabels)
        Create a new Node representation with at least one label, the "primary" label. This is required. All other labels are optional.
        Parameters:
        primaryLabel - The primary label this node is identified by.
        additionalLabels - Additional labels
        Returns:
        A new node representation

      • node

        @NotNull
@Contract(pure=true)
public static @NotNull Node node​(java.lang.String primaryLabel,
                                 java.util.List<java.lang.String> additionalLabels)
        Create a new Node representation with at least one label, the "primary" label. This is required. All other labels are optional.
        Parameters:
        primaryLabel - The primary label this node is identified by.
        additionalLabels - Additional labels
        Returns:
        A new node representation

      • node

        @NotNull
@Contract(pure=true)
public static @NotNull Node node​(java.lang.String primaryLabel,
                                 MapExpression properties,
                                 java.lang.String... additionalLabels)
        Create a new Node representation with at least one label, the "primary" label. This is required. All other labels are optional. This method also takes a map of properties. This allows the returned node object to be used in a MATCH or MERGE statement.
        Parameters:
        primaryLabel - The primary label this node is identified by.
        properties - The properties expected to exist on the node.
        additionalLabels - Additional labels
        Returns:
        A new node representation

      • anyNode

        @NotNull
@Contract(pure=true)
public static @NotNull Node anyNode()
        Returns:
        A node matching any node.

      • asterisk

        @NotNull
@Contract(pure=true)
public static @NotNull Asterisk asterisk()
        Returns:
        The * wildcard literal.

      • anyNode

        @NotNull
@Contract(pure=true)
public static @NotNull Node anyNode​(java.lang.String symbolicName)
        Parameters:
        symbolicName - The new symbolic name
        Returns:
        A node matching any node with the symbolic the given symbolicName.

      • anyNode

        @NotNull
@Contract(pure=true)
public static @NotNull Node anyNode​(SymbolicName symbolicName)
        Parameters:
        symbolicName - The new symbolic name
        Returns:
        A node matching any node with the symbolic the given symbolicName.

      • property

        @NotNull
@Contract(pure=true)
public static @NotNull Property property​(java.lang.String containerName,
                                         java.lang.String... names)
        Dereferences a property for a symbolic name, most likely pointing to a property container like a node or a relationship.
        Parameters:
        containerName - The symbolic name of a property container
        names - The names of the properties to dereference. More than one name does create a nested property like containerName.name1.name2.
        Returns:
        A new property

      • property

        @NotNull
@Contract(pure=true)
public static @NotNull Property property​(Expression expression,
                                         java.lang.String... names)
        Dereferences a property on a arbitrary expression.
        Parameters:
        expression - The expression that describes some sort of accessible map
        names - The names of the properties to dereference. More than one name does create a nested property like expression.name1.name2.
        Returns:
        A new property.

      • property

        @NotNull
@Contract(pure=true)
public static @NotNull Property property​(java.lang.String containerName,
                                         Expression lookup)
        Creates a dynamic lookup of a property for a symbolic name, most likely pointing to a property container like a node or a relationship. A dynamic property will be rendered as p[expression].
        Parameters:
        containerName - The symbolic name of a property container
        lookup - An expression to use as a dynamic lookup for properties of the container with the given name
        Returns:
        A new property
        Since:
        2021.0.0

      • property

        @NotNull
@Contract(pure=true)
public static @NotNull Property property​(Expression expression,
                                         Expression lookup)
        Creates a dynamic lookup of a property on a arbitrary expression. A dynamic property will be rendered as p[expression].
        Parameters:
        expression - The expression that describes some sort of accessible map
        lookup - An expression to use as a dynamic lookup for properties of the container the expression resolved to
        Returns:
        A new property.
        Since:
        2021.0.0

      • path

        @NotNull
@Contract(pure=true)
public static NamedPath.OngoingDefinitionWithName path​(java.lang.String name)
        Starts defining a named path by indicating a name.
        Parameters:
        name - The name of the new path
        Returns:
        An ongoing definition of a named path
        Since:
        1.1

      • path

        @NotNull
@Contract(pure=true)
public static NamedPath.OngoingDefinitionWithName path​(SymbolicName name)
        Starts defining a named path by indicating a name.
        Parameters:
        name - The name of the new path
        Returns:
        An ongoing definition of a named path
        Since:
        1.1

      • shortestPath

        @NotNull
@Contract(pure=true)
public static NamedPath.OngoingShortestPathDefinitionWithName shortestPath​(java.lang.String name)
        Starts defining a named path defined by the shortestPath between a relationship by indicating a name.
        Parameters:
        name - The name of the new shortestPath path
        Returns:
        An ongoing definition of a named path
        Since:
        1.1.1

      • shortestPath

        @NotNull
@Contract(pure=true)
public static NamedPath.OngoingShortestPathDefinitionWithName shortestPath​(SymbolicName name)
        Starts defining a named path defined by the shortestPath between a relationship by indicating a name.
        Parameters:
        name - The name of the new shortestPath path
        Returns:
        An ongoing definition of a named path
        Since:
        1.1.1

      • name

        @NotNull
@Contract(pure=true)
public static @NotNull SymbolicName name​(java.lang.String value)
        Creates a new symbolic name.
        Parameters:
        value - The value of the symbolic name
        Returns:
        A new symbolic name

      • parameter

        @NotNull
@Contract(pure=true)
public static @NotNull Parameter<java.lang.Object> parameter​(java.lang.String name)
        Creates a new parameter placeholder. Existing $-signs will be removed.
        Parameters:
        name - The name of the parameter, must not be null
        Returns:
        The new parameter

      • parameter

        @NotNull
@Contract(pure=true)
public static <T> @NotNull Parameter<T> parameter​(java.lang.String name,
                                                  T value)
        Creates a new parameter with the given name and a value bound to it. The value can be retrieved from the final statement build.
        Type Parameters:
        T - Type of the new parameter
        Parameters:
        name - The name of the parameter, must not be null
        value - The value of the parameter.
        Returns:
        The new parameter
        Since:
        2021.0.0

      • anonParameter

        @NotNull
@Contract(pure=true)
public static <T> @NotNull Parameter<T> anonParameter​(T value)
        Creates a new anonymous parameter with a value bound to it. The value can be retrieved from the final statement build. The name will be available as soon as the statement has been rendered.
        Type Parameters:
        T - Type of the new parameter
        Parameters:
        value - The value of the parameter.
        Returns:
        The new parameter
        Since:
        2021.1.0

      • optionalMatch

        @NotNull
@Contract(pure=true)
public static StatementBuilder.OngoingReadingWithoutWhere optionalMatch​(PatternElement... pattern)
        Prepares an optional match statement.
        Parameters:
        pattern - The patterns to match
        Returns:
        An ongoing match that is used to specify an optional where and a required return clause

      • match

        @NotNull
@Contract(pure=true)
public static StatementBuilder.OngoingReadingWithoutWhere match​(PatternElement... pattern)
        Starts building a statement based on a match clause. Use node(String, String...) and related to retrieve a node or a relationship, which both are pattern elements.
        Parameters:
        pattern - The patterns to match
        Returns:
        An ongoing match that is used to specify an optional where and a required return clause

      • match

        @NotNull
@Contract(pure=true)
public static StatementBuilder.OngoingReadingWithoutWhere match​(boolean optional,
                                                                PatternElement... pattern)
        Starts building a statement based on a match clause. Use node(String, String...) and related to retrieve a node or a relationship, which both are pattern elements.
        Parameters:
        optional - A flag whether the MATCH clause includes the OPTIONAL keyword.
        pattern - The patterns to match
        Returns:
        An ongoing match that is used to specify an optional where and a required return clause
        Since:
        2020.1.3

      • create

        @NotNull
@Contract(pure=true)
public static StatementBuilder.OngoingUpdate create​(PatternElement... pattern)
        Starts building a statement based on a CREATE clause.
        Parameters:
        pattern - The patterns to create
        Returns:
        An ongoing CREATE that can be used to specify WITH and RETURNING etc.

      • with

        @NotNull
@Contract(pure=true)
public static StatementBuilder.OrderableOngoingReadingAndWithWithoutWhere with​(java.lang.String... variables)
        Starts a statement with a leading WITH. Those are useful for passing on lists of various type that can be unwound later on etc. A leading WITH cannot be used with patterns obviously and needs its arguments to have an alias.
        Parameters:
        variables - One ore more variables.
        Returns:
        An ongoing with clause.
        Since:
        2020.1.2

      • with

        @NotNull
@Contract(pure=true)
public static StatementBuilder.OrderableOngoingReadingAndWithWithoutWhere with​(Named... variables)
        Starts a statement with a leading WITH. Those are useful for passing on lists of various type that can be unwound later on etc. A leading WITH cannot be used with patterns obviously and needs its arguments to have an alias.
        Parameters:
        variables - One ore more variables.
        Returns:
        An ongoing with clause.
        Since:
        2020.1.2

      • with

        @NotNull
@Contract(pure=true)
public static StatementBuilder.OrderableOngoingReadingAndWithWithoutWhere with​(Expression... expressions)
        Starts a statement with a leading WITH. Those are useful for passing on lists of various type that can be unwound later on etc. A leading WITH cannot be used with patterns obviously and needs its arguments to have an alias.

        This method takes both aliased and non-aliased expression. The later will produce only valid Cypher when used in combination with a correlated subquery via call(Statement).

        Parameters:
        expressions - One ore more aliased expressions.
        Returns:
        An ongoing with clause.

      • merge

        @NotNull
@Contract(pure=true)
public static StatementBuilder.OngoingMerge merge​(PatternElement... pattern)
        Starts building a statement based on a MERGE clause.
        Parameters:
        pattern - The patterns to merge
        Returns:
        An ongoing MERGE that can be used to specify WITH and RETURNING etc.

      • unwind

        @NotNull
@Contract(pure=true)
public static StatementBuilder.OngoingUnwind unwind​(Expression expression)
        Starts building a statement starting with an UNWIND clause. The expression needs to be an expression evaluating to a list, otherwise the query will fail.
        Parameters:
        expression - The expression to unwind
        Returns:
        An ongoing UNWIND.

      • unwind

        @NotNull
@Contract(pure=true)
public static StatementBuilder.OngoingUnwind unwind​(Expression... expressions)
        Starts building a statement starting with an UNWIND clause. The expressions passed will be turned into a list expression
        Parameters:
        expressions - expressions to unwind
        Returns:
        a new instance of StatementBuilder.OngoingUnwind

      • sort

        @NotNull
@Contract(pure=true)
public static @NotNull SortItem sort​(Expression expression)
        Creates a new SortItem to be used as part of an Order.
        Parameters:
        expression - The expression by which things should be sorted
        Returns:
        A sort item, providing means to specify ascending or descending order

      • mapOf

        @NotNull
@Contract(pure=true)
public static @NotNull MapExpression mapOf​(java.lang.Object... keysAndValues)
        Creates a map of expression from a list of key/value pairs.
        Parameters:
        keysAndValues - A list of key and values. Must be an even number, with alternating String and Expression
        Returns:
        A new map expression.

      • asExpression

        @NotNull
@Contract(pure=true)
public static @NotNull MapExpression asExpression​(java.util.Map<java.lang.String,​java.lang.Object> map)
        Creates a map of expression from a Java Map.
        Parameters:
        map - A map to be turned into a MapExpression
        Returns:
        A new map expression.
        Since:
        2021.1.0

      • listOf

        @NotNull
@Contract(pure=true)
public static @NotNull ListExpression listOf​(Expression... expressions)
        Creates a list-expression from several expressions.
        Parameters:
        expressions - expressions to get combined into a list
        Returns:
        a new instance of ListExpression

      • literalOf

        @NotNull
@Contract(pure=true)
public static <T> @NotNull Literal<T> literalOf​(java.lang.Object object)
        Creates a new Literal<?> from the given object.
        Type Parameters:
        T - The type of the literal returned
        Parameters:
        object - the object to represent.
        Returns:
        a new Literal<?>.
        Throws:
        java.lang.IllegalArgumentException - when the object cannot be represented as a literal

      • literalTrue

        @NotNull
@Contract(pure=true)
public static @NotNull Literal<java.lang.Boolean> literalTrue()
        Returns:
        The true literal.

      • literalFalse

        @NotNull
@Contract(pure=true)
public static @NotNull Literal<java.lang.Boolean> literalFalse()
        Returns:
        The false literal.

      • union

        @NotNull
@Contract(pure=true)
public static @NotNull Statement union​(Statement... statements)
        Creates a UNION statement from several other statements. No checks are applied for matching return types.
        Parameters:
        statements - the statements to union.
        Returns:
        A union statement.

      • unionAll

        @NotNull
@Contract(pure=true)
public static @NotNull Statement unionAll​(Statement... statements)
        Creates a UNION ALL statement from several other statements. No checks are applied for matching return types.
        Parameters:
        statements - the statements to union.
        Returns:
        A union statement.

      • returning

        @NotNull
@Contract(pure=true)
public static StatementBuilder.OngoingReadingAndReturn returning​(Expression... expressions)
        A RETURN statement without a previous match.
        Parameters:
        expressions - The expressions to return
        Returns:
        A buildable statement
        Since:
        1.0.1

      • listBasedOn

        @NotNull
@Contract(pure=true)
public static @NotNull PatternComprehension.OngoingDefinitionWithPattern listBasedOn​(NamedPath namedPath)
        Creates a list comprehension starting with a named path.
        Parameters:
        namedPath - The named path on which the new list comprehension is based on.
        Returns:
        An ongoing definition.
        Since:
        2020.1.1

      • quote

        @NotNull
@Contract(pure=true)
public static @NotNull java.lang.String quote​(java.lang.String unquotedString)
        Escapes and quotes the unquotedString for safe usage in Neo4j-Browser and Shell.
        Parameters:
        unquotedString - An unquoted string
        Returns:
        A quoted string with special chars escaped.

      • caseExpression

        @NotNull
@Contract(pure=true)
public static @NotNull Case caseExpression()
        Returns:
        generic case expression start

      • caseExpression

        @NotNull
@Contract(pure=true)
public static @NotNull Case caseExpression​(Expression expression)
        Parameters:
        expression - initial expression for the simple case statement
        Returns:
        simple case expression start

      • call

        @NotNull
@Contract(pure=true)
public static @NotNull ProcedureCall.OngoingStandaloneCallWithoutArguments call​(java.lang.String procedureName)
        Starts defining a procedure call of the procedure with the given procedureName. That procedure name might be fully qualified - that is, including a namespace - or just a simple name.
        Parameters:
        procedureName - The procedure name of the procedure to call. Might be fully qualified.
        Returns:
        An ongoing definition of a call

      • call

        @NotNull
@Contract(pure=true)
public static @NotNull ProcedureCall.OngoingStandaloneCallWithoutArguments call​(java.lang.String... namespaceAndProcedure)
        Starts defining a procedure call of the procedure with the given qualified name.
        Parameters:
        namespaceAndProcedure - The procedure name of the procedure to call.
        Returns:
        An ongoing definition of a call

      • subList

        @NotNull
@Contract(pure=true)
public static @NotNull Expression subList​(Expression targetExpression,
                                          java.lang.Integer start,
                                          java.lang.Integer end)
        Creates a closed range with given boundaries.
        Parameters:
        targetExpression - The target expression for the range
        start - The inclusive start
        end - The exclusive end
        Returns:
        A range literal.
        Since:
        2020.1.0

      • subList

        @NotNull
@Contract(pure=true)
public static @NotNull Expression subList​(Expression targetExpression,
                                          Expression start,
                                          Expression end)
        Creates a closed range with given boundaries.
        Parameters:
        targetExpression - The target expression for the range
        start - The inclusive start
        end - The exclusive end
        Returns:
        A range literal.
        Since:
        2020.1.0

      • subListFrom

        @NotNull
@Contract(pure=true)
public static @NotNull Expression subListFrom​(Expression targetExpression,
                                              java.lang.Integer start)
        Creates an open range starting at start.
        Parameters:
        targetExpression - The target expression for the range
        start - The inclusive start
        Returns:
        A range literal.
        Since:
        2020.1.0

      • subListFrom

        @NotNull
@Contract(pure=true)
public static @NotNull Expression subListFrom​(Expression targetExpression,
                                              Expression start)
        Creates an open range starting at start.
        Parameters:
        targetExpression - The target expression for the range
        start - The inclusive start
        Returns:
        A range literal.
        Since:
        2020.1.0

      • subListUntil

        @NotNull
@Contract(pure=true)
public static @NotNull Expression subListUntil​(Expression targetExpression,
                                               java.lang.Integer end)
        Creates an open range starting at start.
        Parameters:
        targetExpression - The target expression for the range
        end - The exclusive end
        Returns:
        A range literal.
        Since:
        2020.1.0

      • subListUntil

        @NotNull
@Contract(pure=true)
public static @NotNull Expression subListUntil​(Expression targetExpression,
                                               Expression end)
        Creates an open range starting at start.
        Parameters:
        targetExpression - The target expression for the range
        end - The exclusive end
        Returns:
        A range literal.
        Since:
        2020.1.0

      • valueAt

        @NotNull
@Contract(pure=true)
public static @NotNull ListOperator valueAt​(Expression targetExpression,
                                            java.lang.Integer index)
        Creates a single valued range at index.
        Parameters:
        targetExpression - The target expression for the range
        index - The index of the range
        Returns:
        A range literal.
        Since:
        2020.1.0

      • valueAt

        @NotNull
@Contract(pure=true)
public static @NotNull ListOperator valueAt​(Expression targetExpression,
                                            Expression index)
        Creates a single valued range at index.
        Parameters:
        targetExpression - The target expression for the range
        index - The index of the range
        Returns:
        A range literal.
        Since:
        2020.1.0

      • raw

        @NotNull
@Contract(pure=true)
public static @NotNull Expression raw​(java.lang.String format,
                                      java.lang.Object... mixedArgs)
        Creates an expression from a raw string fragment. No validation is performed on it. If it is used as expression, you must make sure to define something that works as expression.

        This method expects exactly one placeholder in the form of $E for any argument passed with mixedArgs.

        To use exactly the term $E escape it like this: \$E

        Parameters:
        format - A raw Cypher string
        mixedArgs - Args to the Cypher string
        Returns:
        An expression to reuse with the builder.
        Since:
        2021.0.2

      • adapt

        @NotNull
@Contract(pure=true)
public static <FE> @NotNull ForeignAdapter<FE> adapt​(FE expression)
        Provides access to the foreign DSL adapter. Please make sure you have the necessary runtime dependencies on the class path, otherwise you will see some kind of ClassNotFoundException along various classes related to the foreign DSL.
        Returns:
        A foreign adapter
        Throws:
        java.lang.IllegalArgumentException - in case the object cannot be adapter
        Since:
        2021.1.0