🚀 Features

• Add support for QueryDSL's equalsIgnoreCase operator
• GH-204 - Provide access to identifiable expressions (See Retrieving identifiable expressions)

🧹 Housekeeping

• Fix several (compile) warnings
• Fix several spelling errors in api docs
• Upgrade Spring Data Neo4j to 6.1.5 (In module org.neo4j.cypherdsl.codegen.sdn6)
• Upgrade Neo4j Cypher Parser to 4.3.4 (In module neo4j-cypher-dsl-parser).
• Verify examples on JDK 17

2021.3.1 is a pure bug fix release. API Guardian cannot be an optional dependency, otherwise compiling programs with -Werror
will fail, as the @API-annotation has runtime and not class retention.

🐛 Bug Fixes

• GH-203 - Introduce a scope for the PatternComprehension.
• Revert "GH-202 - Make API Guardian an optional / provided dependency."
• Support empty BooleanBuilder in QueryDSL adapter.

2021.3 builds straight upon 2021.2.3, with few additions to the existing API, that didn’t quite fit with a patch release, but belong conceptually into this release, which brings a completely new module: The neo4j-cypher-dsl-parser.

🚀 New module: The Cypher-DSL-Parser

What’s behind that name? A Cypher-Parser build on the official Neo4j 4.3 parser frontend and creating a Cypher-DSL-AST or single expressions usable in the context of the Cypher-DSL.

The module lives under the following coordinates org.neo4j:neo4j-cypher-dsl-parser and requires JDK 11+ (the same version like Neo4j does). We created a couple of examples, but we are sure you will have tons of more ideas and therefore a looking for your feedback, regardless if we missed out something in the API, bugs or just remarks.

Here’s a sneak preview. It shows you can add a user supplied Cypher fragment to something you are building using the DSL.

var userProvidedCypher
    = "MATCH (this)-[:LINK]-(o:Other) RETURN o as result";
var userStatement = CypherParser.parse(userProvidedCypher);

var node = Cypher.node("Node").named("node");
var result = Cypher.name("result");
var cypher = Cypher
    .match(node)
    .call(
        userStatement,
        node.as("this")
    )
    .returning(result.project("foo", "bar"))
    .build()
    .getCypher();

For this release a big thank you goes out to the Cypher-operations team at Neo4j, listening to our requests and ideas!

2021.2.3 is a rather big release as it contains many small improvements and API functionality required by our next major
release. Those are brought in now so that they can be benefial to others without bumping a major version.

🚀 Features

• GH-195 - Add collection parameter support for ExposesReturning.
• Introduce a ExposesPatternLengthAccessors for uniform access to relationships and chains thereof. [improvement]
• Allow creating instances of FunctionInvocation directly. [improvement]
• Provide factory methods of MapProjection and KeyValueMapEntry as public API.
• Provide set and remove labels operation as public API.
• Provide set and mutate of expressions as public API.
• Provide factory methods of Hints as public API.
• GH-200 - Provide an API to define named paths based on a Node pattern.
• Provide an option to escape names only when necessary. [improvement]

📖 Documentation

• Add documentation for escaping names.
• GH-198 - Fix spelling errors in JavaDoc and documentation.

🐛 Bug Fixes

• Make Case an interface and let it extend Expression. [bug]
• GH-197 - Fix eagerly resolved symbolic names in negated pattern conditions.
• GH-197 - Clear name cache after leaving a statement.
• GH-199 - Bring back with(Named… vars).

🧹 Housekeeping

• Don't use fixed driver versions in doc.
• Pass builder as constructor argument.
• Improve Return and With internals.
• Update Driver, SDN integration and Spring Boot example dependencies.
• GH-202 - Make API Guardian an optional / provided dependency.

Thanks to @meistermeier and @aldrinm for their contributions.

🚀 Features

• Allow all expressions to be used as conditions. [improvement]
• Add support for unary minus and plus operations. [new-feature]
• Add support for generatic dynamic distinct aggregating function calls. [new-feature]
• GH-190 - Introduce a union type for named things and aliased expressions.
• Provide means to pass additional types to the relationship base class. [new-feature]
• GH-193 - Allow MATCH after YIELD.
• GH-189 - Provide an alternate api for methods consuming collections via vargs.

📖 Documentation

• Improve inheritance example. [static-model, codegen]

🐛 Bug Fixes

• Fix parameter collector when running as GraalVM native image
• GH-192 - Don't introduce new symbolic names in conditional pattern expressions.

🧹 Housekeeping

• GH-178 - Upgrade SDN 6 examples to Spring Boot 2.5 final.

Thanks to @meistermeier for the contribution of the API improvements in regard to collections.

Now with optional driver integration and executable results. Please have a look at the new section in the docs: http://neo4j-contrib.github.io/cypher-dsl/current/#driver-integration

🚀 Features

• Distinguish between statements and result statements: The Cypher-DSL knows whether a statement would actually return
  data or not
• Provide optional integration with the Neo4j-Java-Driver to execute statements.
• Allow to register Spring converters with the annotation processor. [codegen]
• GH-182 - Add support for scalar converter functions.
• GH-183 - Add trim function.
• GH-184 - Add split function.
• GH-180 - Add support for LOAD CSV and friends.
• GH-187 - Add returningRaw for returning arbitrary (aliased) Cypher fragments (bot as part of a statement or as a
  general RETURN xxx clause without preceding query)
• Resolve named parameters in raw literals: You can mix now the expression placeholder $E and named parameters in raw
  Cypher literals giving you much more flexibility in regards what to pass to the raw litera.

🐛 Bug Fixes

• GH-177 - Create a valid loadable and instantiable name when working on nested, inner classes. [codegen]
• GH-186 - Pretty print subqueries and fix double rendering of Labels after subquery.

🧹 Housekeeping

• Remove unnecessary subpackage 'valid'. [codegen] (test code only)
• Upgrade to GraalVM 21.1.0.
• Update Spring dependencies for codegen.

Thanks to @Andy2003 for contributing to this release.

2021.2 doesn't bring any new features apart from being now a Java library supporting the Java module system not only with automatic module names but also with a correct module-info.java when running on JDK 11+ on the module path.

The Cypher-DSL uses the technique of JEP 238: Multi-Release JAR Files to provide a module-info.java for projects being on JDK 11+.

The MR-Jar allows us to compile for JDK 8 but also support JDK 11 (we choose 11 as it is the current LTS release as time of writing).

To use the Cypher-DSL in a modular application you would need to require the following modules:

module org.neo4j.cypherdsl.examples.core {

	requires org.neo4j.cypherdsl.core;
}

This release comes with a small catch: We do support using some QueryDSL features. Query-DSL will have correct automatic module names in their 5.x release and we asked them to backport those to the 4.x line on which the Cypher-DSL optionally depends (See 2805).

Until then we statically require (that is "optional" in module speak) Query-DSL via the artifact name. This can cause errors when the artifact (querydsl-core.jar) is renamed via the build process or similar. We are gonna improve that as soon as we can depend on fixed automatic module names.

Apart from this big change there is no change in any public API. This release should be a drop-in replacement for the prior.

A big thank you to @sormuras for his invaluable lessons about the Java module system.

This release comes with two notable things: It uses a couple of annotations on the API to guide developers using it correctly. IDEs like IDEA will now issue warnings if you don't use a returned builder, or a new instance of an object while wrongly assuming you mutated state.

In the light of that we discovered that the RelationshipChain pattern was mutable and returning a mutated instance while it should have returned a fresh one.

Warning This might be a breaking change for users having code like this:

var pattern = Cypher.node("Start").named("s")
  .relationshipTo(Cypher.anyNode())
  .relationshipTo(Cypher.node("End").named("e"));
pattern.named("x");

Prior to 2021.1.2 this would give the pattern the name x and modify it in place.
From 2021.1.2 onwards you must use the returned value:

pattern = pattern.named("x");

We think that this change is crucial and necessary as all other patterns are immutable as intended and in sum, they build
up truly immutable statements. One pattern that is mutable like the above invalides the whole guarantee about the statement.

🚀 Features

• Add named(SymbolicName s) to RelationshipChain.
• Generate $TYPE field containing the relationship type. [SDN 6 Annotation Processor]
• Introduce some optional annotations for guidance along the api.

📖 Documentation

• GH-173 - Improve documentation. [A collection of small improvements]

🐛 Bug Fixes

• GH-174 - Extract types via the visitor API and avoid casting element types. [SDN 6 Annotation Processor]
• Ensure immutability of RelationshipChain.

🧹 Housekeeping

• Remove unnecessary close (will be taken care of via @Container). [Only test related]
• Run tests on JDK 16

This is a drop-in replacement for 2021.1.0. Introducing the interface for Property broke the mutate operation, for which no test was in place. This and the bug has been fixed.

🐛 Bug Fixes

• GH-168 - Fix mutating containers by properties.

2021.1.0 comes with a ton of new features and a handful of breaking changes. Fear not, the breaking changes are resolvable by recompiling your application. We turned Node, Relationship and Property into interfaces and provide now NodeBase and RelationshipBase so that you can use them to build a static meta-model of your application. A PropertyBase might follow.

Find out everything about the new possibility to define a static meta model in the manual. The manual also includes a major part about the two new modules we offer: org.neo4j:neo4j-cypher-dsl-codegen-core and org.neo4j:neo4j-cypher-dsl-codegen-sdn6. neo4j-cypher-dsl-codegen-core provides the infrastructure necessary to build code generators for creating a domain model following our recommendation and neo4j-cypher-dsl-codegen-sdn6 is a first implementation of that: A Java annotation processor that can be added to any Spring Data Neo4j 6 project in version 6.0.6 or higher. It will find your annotated domain classes and turn them into a model you can use to build queries.

Last but not least: We added support for some expressions of the more generic QueryDSL. This will require com.querydsl:querydsl-core on the class path but only if you decide to call Cypher#adapt(foreignExpression). This is a feature that is driven by Spring Data Neo4j 6.1 in which we build upon this to provide a QuerydslPredicateExecutor. Find more in this section of the manual.

🚀 Features

• GH-154 - Make Node and Relationship extendable.
• GH-155 - Provide infrastructure for generating a static meta model.
• GH-156 - Create an annotation processor for Spring Data Neo4j 6.
• GH-167 - Add support for some Query-DSL expressions.
• Introduce a statement context for allowing anonymous parameters (use Cypher#anonParameter() to define a parameter with a value but without a name. The name will be accessible on the statement after rendering).
• Make rendering of constants as parameters configurable.
• Allow specification of the direction while creating a sort item.
• Introduce an interface for Property.

📖 Documentation

• GH-152 - Document usage of PatterElement in tests.
• GH-164 - Improve public extendable API and add documentation.

🐛 Bug Fixes

• Fix SymbolicName#toString.
• Clear visited name cache after single queries.

🧹 Housekeeping

• GH-165 - Simplify poms.
• GH-166 - Improve Cypher.literalOf.
• Exclude all example projects from release.

WARNING: This will already be the last release of the 2021.0 line. 2021.1 will be API compatible but not ABI compatible, as some classes have been changed into interfaces. That means it is not a drop in replacement, but your application needs to be recompiled.

🚀 Features

• GH-157 - Provide a method to turn a Java map into an expression.
• GH-158 - Improve pretty printing of subqueries.
• Allow the use of raw cypher as expressions.
• Allow symbolic names to be used as aliases.
• Cache some symbolic names.
• Add support for the keys() function.

📖 Documentation

• GH-152 - Document usage of PatterElement in tests.

🐛 Bug Fixes

• GH-149 - Avoid possible stackoverflow exception during visitor traversal.
• GH-159 - Fix missing labels for nodes after WITH.

🧹 Housekeeping

• GH-148 - Add jQAssistant rules and improve building documentation.
• Add Maven PMD plugin.

Thanks @Andy2003 for the improvements of the pretty printer.

🚀 Features

• GH-147 - Configuration infrastructure for renderer. First use case being a simple, pretty printing renderer.

The feature looks like this:

var c = node("Configuration").named("c");
var d = node("Cypher-DSL").named("d");

var mergeStatement = merge(c.relationshipTo(d, "CONFIGURES"))
    .onCreate()
        .set(
            d.property("version").to(literalOf("2021.0.1")),
            c.property("prettyPrint").to(literalTrue())
        )
    .onMatch().set(c.property("indentStyle").to(literalOf("TAB")))
    .returning(d).build();

var renderer = Renderer.getRenderer(Configuration.prettyPrinting());
System.out.println(renderer.render(mergeStatement));

and gives you:

MERGE (c:Configuration)-[:CONFIGURES]->(d:`Cypher-DSL`)
  ON CREATE SET d.version = '2021.0.1', c.prettyPrint = true
  ON MATCH SET c.indentStyle = 'TAB'
RETURN d

2021.0.0 comes with a lot of new features.

Thanks to @Andy2003 for his contributions!

Andy is one of our first users outside Spring Data Neo4j 6 and he started to use the Cypher-DSL in Neo4j GraphQL Java. Neo4j GraphQL Java is a library to translate GraphQL based schemas and queries to Cypher and execute those statements with the Neo4j database.
It can be used from a wide variety of frameworks.

We are happy and proud to be part of this and even more so about the input and contribution we got back from Andy.

Of course thanks for your input in form of tickets and discussions go out to @utnaf, @aaramg, @K-Lovelace and @maximelovino as well!

Noteworthy

Two things should be mentioned:

The bugfix for GH-121 might change behavior for some users: The changes prevents the forced rendering of an alias for objects when the original object - the one that has been aliased - is passed down to the DSL after an alias has been created.

The original intention for that behaviour was related to Map projection, in which the alias is actually rendered before the object.

So now the use of an aliased expression the first time triggers a AS b respectively b: a in a map projection. All further calls will just render b. If the original object is used again, a will be rendered. If that is not desired in your query and you rely on the alias, make sure you use the aliased expression returned from .as("someAlias").

The other thing are the combined features GH-135 and GH-146. The Statement class has become a fully fledged accessor to the Cypher String and the parameters used and if provided, the values for those. The following shows a small example:

var person = Cypher.node("Person").named("p");
var statement = Cypher
    .match(person)
    .where(person.property("nickname").isEqualTo(Cypher.parameter("nickname")))
    .set(
        person.property("firstName").to(Cypher.parameter("firstName").withValue("Thomas")),
        person.property("name").to(Cypher.parameter("name", "Anderson"))
    )
    .returning(person)
    .build();

assertThat(statement.getCypher())
    .isEqualTo("MATCH (p:`Person`) WHERE p.nickname = $nickname SET p.firstName = $firstName, p.name = $name RETURN p");

Collection<String> parameterNames = statement.getParameterNames();
assertThat(parameterNames).containsExactlyInAnyOrder("nickname", "firstName", "name");

Map<String, Object> parameters = statement.getParameters();
assertThat(parameters).hasSize(2);
assertThat(parameters).containsEntry("firstName", "Thomas");
assertThat(parameters).containsEntry("name", "Anderson");

What's Changed

🚀 Features

• GH-122 - Add support for index hints.
• GH-123 - Expose nested building of nested properties as public API.
• GH-124 - Add support for Neo4j's mathematical functions.
• GH-127 - Allow dynamic property lookup.
• GH-128 - Provide asConditions for RelationshipPatterns.
• GH-129 - Allow Expressions as Parameter for Skip and Limit.
• GH-131 - Add support for projections on symbolic names.
• GH-133 - Allow symbolic names to be used as condition.
• GH-135 - Collect parameters defined on a statement.
• GH-141 - Provide a property function on all expressions.
• GH-142 - Provide a point function accepting generic expressions as parameter.
• GH-146 - Allow a statement to render itself.

📖 Documentation

• GH-126 - Document how to call arbitrary functions and procedures.

🐛 Bug Fixes

• Prevent double rendering of Node content when using generated names.
• GH-121 - Don't force rendering of aliases when the original object is used.
• GH-137 - Fix grouping of nested conditions.

🧹 Housekeeping

• Switch to GraalVM 20.3.0.
• GH-125 - Use GraalVM image from ghcr.io.
• GH-139 - Ensure indention via tabs.
• GH-140 - Provide editorconfig.
• GH-143 - Remove union types.

No new features.
Re-released 2020.1.5 due downtime and staging issues of oss.sonatype.org.

What's Changed

🚀 Features

• GH-116 - Add support for creating calls to Neo4j reduce().
• GH-119 - Add support for passing symbolic names to nodes and relationships functions.
• GH-117 - Introduce mutating operator.

What's Changed

🚀 Features

• GH-114 - Support chained properties.
• GH-115 - Support named items in YIELD and symbolic names as NamedPath reference.

What's Changed

🚀 Features

• GH-111 - Provide a programmatic way of creating an optional match.

🐛 Bug Fixes

• GH-110 - Fix collapsing of empty conditions.

What's Changed

🚀 Features

• GH-88 - Add support for Neo4j 4.0 subqueries.
• GH-104 - Add support for merge actions.
• GH-101 - Introduce asFunction on an ongoing call definition.

Additional new features:

• Add support for EXPLAIN and PROFILE keywords.

We do publish the Project info now: Project info, including the Java API.

🐛 Bug Fixes

• GH-106 - Escape symbolic names, property lookups, aliases and map keys.

🧹 Housekeeping

• GH-105 - Remove ::set-env from GH-Actions ci.

Further improvements:

• Qualify a yield call (only relevant for JDK15+)
• Fix wrong offsets in the documentation.
• Improve JavaDoc and document internal API.
• Allow WITH clause after YIELD.
• Improve reusability of fragments.
• Make ORDER clause buildable.
• Remove parts of an experimental API.

What's Changed

🚀 Features

• List comprehensions can now be build based on named paths.

What's Changed

🚀 Features

• GH-74 - Automatically generate symbolic name if required: Node and Relationship objects generate a symbolic name if required and not set
• Added several new functions
  • GH-77 properties()
  • GH-81 relationships()
  • GH-83 startNode(), endNode(),
  • GH-89 All temporal functions
• GH-76 - Added the list operator ([] for accessing sub lists and indexes).

🐛 Bug Fixes

• GH-82 - Expose all necessary interfaces for call
• GH-84 - Fix rendering of nested sub trees.
• GH-95 - NPE during the creation of map projections
• GH-96 - Make sure aliased expressions are not rendered multiple times.

🧹 Housekeeping

• GH-67 - Improvements in regards of Java generics.
• GH-68 - Clean up the Functions api.
• GH-69 - Avoid star and static imports.
• GH-72 - Some release cleanup
• GH-75 - Move Assert to internal utils package.
• GH-89 - RelationshipDetails is now internal API.
• GH-93 - Ensure compatibility with GraalVM native.
• GH-94 - Bring back SymbolicName#concat.