Releases: neo4j/cypher-dsl
2021.3.1
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
2021.3.0
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
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
andKeyValueMapEntry
as public API. - Provide
set
andremove
labels operation as public API. - Provide
set
andmutate
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 extendExpression
. [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
andWith
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.
2021.2.2
🚀 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.
2021.2.1
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
generalRETURN 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.0
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.
2021.1.2
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
2021.1.1
2021.1.0
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
2021.0.2
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.