Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
179099a
fix(neo4j): isNull and isNotNull on an association test the relationship
borinquenkid Nov 3, 2026
5f50268
Neo4j: a null test in an association block is made on the associated …
borinquenkid Nov 5, 2026
4271678
fix(neo4j): test the properties of a relationship entity block as pro…
borinquenkid Nov 6, 2026
1da133a
fix(neo4j): compare an association by the identity of the associated …
borinquenkid Nov 7, 2026
0ad7f66
fix(neo4j): the criteria of a relationship block use the identity of …
borinquenkid Nov 9, 2026
63657b7
Merge 8.0.x into fix/neo4j-isnull-association-8.0.x
borinquenkid Nov 9, 2026
6e861ac
fix(neo4j): qualify the plain properties of a relationship with its v…
borinquenkid Nov 9, 2026
c5bf41a
fix(neo4j): a null test on an association to a relationship entity na…
borinquenkid Nov 10, 2026
ff5c7e3
refactor(neo4j): decide what a property refers to in one place, Crite…
borinquenkid Nov 10, 2026
12e1fcc
fix(neo4j): a block on a relationship entity is scoped to the relatio…
borinquenkid Nov 10, 2026
6bb0d55
fix(neo4j): test an association where it stands inside a disjunction,…
borinquenkid Nov 11, 2026
1393d5f
Merge 8.0.x into fix/neo4j-isnull-association-8.0.x
borinquenkid Nov 12, 2026
9de206c
fix(neo4j): a criterion on a collection holds when some element satis…
borinquenkid Nov 14, 2026
af3f608
fix(neo4j): a criterion on a collection holds when some element satis…
borinquenkid Nov 15, 2026
636834f
fix(neo4j): an end of a relationship in a block is compared through t…
borinquenkid Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@
import java.util.List;
import java.util.Map;

import org.grails.datastore.mapping.model.PersistentEntity;

/**
* A builder for Cypher queries
*
Expand Down Expand Up @@ -66,6 +68,8 @@ public class CypherBuilder {
private final List<String> matches = new ArrayList<>();
private final List<String> relationshipMatches = new ArrayList<>();
private final List<String> optionalMatches = new ArrayList<String>();
private int disjunctionDepth;
private int localNumber;
private String conditions;
private String orderAndLimits;
private final List<String> returnColumns = new ArrayList<String>();
Expand Down Expand Up @@ -157,10 +161,63 @@ public void addOptionalMatch(String match) {
optionalMatches.add(match);
}

private final Map<String, PersistentEntity> relationshipVariables = new LinkedHashMap<>();

/**
* Records that a variable of the query stands for a relationship, so a criterion on it is about the
* relationship's own properties, identified as that relationship entity maps them, and not about the
* relationships or the identity of a node.
*
* @param variable the variable of the relationship
* @param relationshipEntity the relationship entity the variable stands for
*/
public void addRelationshipVariable(String variable, PersistentEntity relationshipEntity) {
relationshipVariables.put(variable, relationshipEntity);
}

public boolean isRelationshipVariable(String variable) {
return relationshipVariables.containsKey(variable);
}

/**
* @param variable a variable of the query
* @return the relationship entity the variable stands for, or {@code null} when it does not stand for a relationship
*/
public PersistentEntity getRelationshipEntity(String variable) {
return relationshipVariables.get(variable);
}

public int getNextMatchNumber() {
return matches.size();
}

/**
* Marks the start of a disjunction: a criterion in it must not narrow the rows the other branches see, so it
* tests for what it needs where it stands and adds no match to the query.
*/
public void enterDisjunction() {
disjunctionDepth++;
}

public void leaveDisjunction() {
disjunctionDepth--;
}

/**
* @return whether the criterion being built is inside a disjunction
*/
public boolean isInDisjunction() {
return disjunctionDepth > 0;
}

/**
* @return a number for a variable that is local to one expression of the conditions, such as the node of an
* existence test, and cannot clash with a variable of the matches
*/
public int nextLocalNumber() {
return localNumber++;
}

public void setConditions(String conditions) {
this.conditions = conditions;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -124,13 +124,21 @@ ON CREATE SET r = row.props"""

@Override
String formatProperty(String variable, String property) {
if (property.startsWith(FROM) || property.startsWith(TO)) {
if (isEnd(property, FROM) || isEnd(property, TO)) {
return property
} else {
return super.formatProperty(variable, property)
}
}

/**
* Whether a property name is the end of the relationship itself or something of that end ({@code to},
* {@code to.name}), and not a property that merely starts with the same letters, like {@code total}.
*/
private static boolean isEnd(String property, String end) {
property == end || property.startsWith(end + '.')
}

@Override
String formatMatchId(String variable) {
return String.format(MATCH_ID, buildMatch(type(), CypherBuilder.NODE_VAR), formatId())
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,10 @@ class RelationshipUtils {
static String matchForRelationshipEntity(Association association, RelationshipPersistentEntity entity, String var = 'r') {
Attribute mappedForm = (Attribute) association.getMapping()?.getMappedForm()
PersistentEntity owningEntity = association.getOwner()
Direction direction = mappedForm.direction ?: owningEntity == entity.getTo().associatedEntity ? Direction.INCOMING : Direction.OUTGOING
// the owner is at the receiving end only when it is not also the origin: a relationship between two nodes of one type
// is entered from its origin, as navigating the association of an instance does
boolean receiving = owningEntity == entity.getTo().associatedEntity && owningEntity != entity.getFrom().associatedEntity
Direction direction = mappedForm.direction ?: receiving ? Direction.INCOMING : Direction.OUTGOING
final boolean reversed = direction == Direction.INCOMING || direction == Direction.BOTH
StringBuilder sb = new StringBuilder()
if (reversed) {
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,259 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.grails.datastore.gorm.neo4j.engine

import groovy.transform.CompileStatic

import org.grails.datastore.gorm.neo4j.CypherBuilder
import org.grails.datastore.gorm.neo4j.GraphPersistentEntity
import org.grails.datastore.gorm.neo4j.RelationshipPersistentEntity
import org.grails.datastore.mapping.model.PersistentEntity
import org.grails.datastore.mapping.model.PersistentProperty
import org.grails.datastore.mapping.model.types.Association
import org.grails.datastore.mapping.model.types.Basic
import org.grails.datastore.mapping.model.types.Embedded
import org.grails.datastore.mapping.model.types.ToMany
import org.grails.datastore.mapping.model.types.ToOne
import org.grails.datastore.mapping.query.AssociationQuery

/**
* What a criterion of a Neo4j query is about: the entity whose properties it names, the Cypher variable that
* entity is matched to, and the query being built. Every decision about what a property name refers to, in the
* root of a query or in the block of an association, is made here, so a criterion handler only says what it
* compares and never works out where the property is.
*
* <p>A scope is for a node, or for the relationship of an association to a relationship entity, whose properties
* are the relationship's own and which has no relationships to test.</p>
*
* @since 8.0.1
*/
@CompileStatic
final class CriterionScope {

final GraphPersistentEntity entity
final CypherBuilder builder
final String variable
/** The variables of the nodes at the ends of the relationship, when this is the scope of a relationship block. */
final String fromVariable
final String toVariable

CriterionScope(GraphPersistentEntity entity, CypherBuilder builder, String variable,
String fromVariable = null, String toVariable = null) {
this.entity = entity
this.builder = builder
this.variable = variable
this.fromVariable = fromVariable
this.toVariable = toVariable
}

/**
* The variable of the node a {@code from} or {@code to} block of a relationship refers to: the end of the
* relationship the block was entered through, or the one of the root query when the relationship is the root.
*/
String endVariable(String end) {
String found = end == RelationshipPersistentEntity.TO ? toVariable : fromVariable
found ?: end
}

/**
* The same entity, matched to another variable.
*/
CriterionScope atVariable(String otherVariable) {
new CriterionScope(entity, builder, otherVariable)
}

/**
* Whether the variable is that of a relationship, as it is in a block on an association to a relationship
* entity.
*/
boolean isRelationship() {
entity.isRelationshipEntity() || builder.isRelationshipVariable(variable)
}

/**
* The scope of a block on an end of the relationship of this scope, a {@code from} or {@code to} association:
* the node at that end, which is already matched, so its criteria are about the entity the end refers to.
*/
CriterionScope forEnd(Association end) {
PersistentEntity node = end.associatedEntity
if (fromVariable == null || !(node instanceof GraphPersistentEntity)) {
return atVariable(end.name)
}
new CriterionScope((GraphPersistentEntity) node, builder, endVariable(end.name))
}

/**
* The identity of the entity of this scope.
*/
String id() {
entity.formatId(variable)
}

/**
* A plain property of this scope, qualified with its variable.
*/
String property(String name) {
entity.formatProperty(variable, name)
}

/**
* What a property name refers to as one side of a comparison: the identity of the node an association
* reaches, which is matched for it, the identity of an end of a relationship, the type of a relationship, or
* a plain property.
*/
String reference(String name) {
PersistentProperty found = entity.getPropertyByName(name)
if (found instanceof Association && !(found instanceof Basic)) {
Association association = (Association) found
GraphPersistentEntity associated = (GraphPersistentEntity) association.associatedEntity
if (entity.isRelationshipEntity() && RelationshipPersistentEntity.isRelationshipAssociation(association)) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

links { eq('to', target) } should match the links that end at that target. The query names to, and that name was never bound, so the query fails. Use the variable the block already bound for that end.

// an end of the relationship is the node the block bound for it; when the relationship is the root of the query
// the end is named by the pattern itself
return associated.formatId(endVariable(association.name))
}
if (builder.inDisjunction && found instanceof ToOne) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or { eq('name', 's2'); inList('items', [i1.id]) }, where s2 has no items. The list returns only the shelf that has i1. s2 is dropped before the name test can keep it. Do not require the collection for the whole query.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 9de206c. The disjunction case was one cell of a class: a criterion on a collection (inList, eq, the comparisons) took a required match of the collection, in any or or not. It is now read in place and holds when some element satisfies it, so s2 reaches the name branch. isEmpty and isNotEmpty on an association had the same family of problem (they tested a node property that does not exist) and now test the relationship, like isNull.

CollectionAssociationMatrixSpec covers 10 criteria in 6 contexts (top level, either side of an or, an and in an or, an or in an and, not), from the root and from a nested block: 120 cases, and 28 of the first 36 failed before the change. The whole Neo4j core suite passes (906 tests, 0 failures).

// in a disjunction the node reached is read where it stands: a match would drop the nodes that have
// none before the other branches could keep them, and a missing node is a null the branch does not match
String local = "e_${builder.nextLocalNumber()}"
String pattern = entity.formatAssociationPatternFromExisting(association, '', variable, local)
return "head([${pattern} | ${associated.formatId(local)}])".toString()
}
String target = "m_${builder.getNextMatchNumber()}"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shelf s1 has one item i1. inList('items', [i1.id]) twice should return s1. It returns nothing. Each criterion adds another relationship pattern, and those patterns are combined into one match that cannot reuse the only relationship. A collection criterion should hold when some element satisfies it, including when the same element satisfies two of them.

builder.addMatch(entity.formatAssociationPatternFromExisting(association, '', variable, target))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or { eq('name', 'Other'); inList('parent', [other.id]) }, with Other having no parent. The list returns only the child. Other is dropped before the name test can keep it. Do not require the association for the whole query.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 6bb0d55. Inside an or, an association reference no longer adds a required MATCH. A to-one reference is read in place with head([pattern | id]), and an association block is an existence test, size([pattern WHERE conditions | 1]) > 0. A node without the association is a null the branch does not match, so the other branches can still keep it. (The embedded server's driver rejects EXISTS { }, hence the pattern comprehensions.) Your or { eq('name','Other'); inList('parent', [other.id]) } case is in RelationshipBlockMatrixSpec, with the other criteria in or (block, eq, in, isNull, isNotNull).

Known limit: a to-many reference compared inside or still uses the required match, because a comprehension can read only one node. Blocks and null tests on to-many associations are fine.

The same behavior is documented for Hibernate ("accounts that have either performed transactions OR were recently created"), and the same bug on Hibernate 5 and 7 is in #16924, with fixes in #16930 and #16931.

// the node reached is of the associated entity, whose identity may be mapped differently
return associated.formatId(target)
}
if (entity.isRelationshipEntity() && name == RelationshipPersistentEntity.TYPE) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

links { eq('type', 'COLLINK') } should match the links of that type. The query names r, and the block bound the relationship as another variable, so the owner is dropped. Use the variable the block already bound.

builder.replaceFirstRelationshipMatch(((RelationshipPersistentEntity) entity).buildRelationshipMatchTo(null, CypherBuilder.REL_VAR))
return "TYPE(${CypherBuilder.REL_VAR})".toString()
}
property(name)
}

/**
* Whether a criterion on the property is about a collection of nodes, which is read where it stands. A match
* would require the collection for the whole query, which drops the nodes that have none before the other
* branches of a disjunction could keep them, and it would give each criterion a relationship of its own, which
* Cypher does not let two patterns of one match share, so two criteria that the same element satisfies would
* find nothing. A criterion on a collection holds when some element satisfies it, in any context.
*
* @param name The property name
* @return True for a collection of nodes
*/
boolean readsMembers(String name) {
if (entity.isRelationshipEntity()) {
return false
}
PersistentProperty found = entity.getPropertyByName(name)
found instanceof ToMany && !(found instanceof Basic) && !(found instanceof Embedded)
}

/**
* The identities of the nodes in a collection, read where the collection stands.
*
* @param name The name of a property for which {@link #readsMembers} is true
* @return A list expression
*/
String members(String name) {
Association association = (Association) entity.getPropertyByName(name)
GraphPersistentEntity associated = (GraphPersistentEntity) association.associatedEntity
String local = "e_${builder.nextLocalNumber()}"
String pattern = entity.formatAssociationPatternFromExisting(association, '', variable, local)
"[${pattern} | ${associated.formatId(local)}]".toString()
}

/**
* The pattern that holds when the node has a relationship for the association, or {@code null} when the
* property is not an association stored as a relationship. An association is not a property of the node, so
* a null test on it has to look for the relationship and not for a node property. A basic collection and an
* embedded component are stored on the node itself, and the properties of a relationship have no
* relationships, so they stay a null test of the property. An association to a relationship entity is the
* relationships of that entity's type, so the pattern names the type.
*/
String associationPattern(String name) {
if (relationship) {
return null
}
PersistentProperty found = entity.getPropertyByName(name)
if (found instanceof Association && !(found instanceof Basic) && !(found instanceof Embedded)) {
PersistentEntity associated = ((Association) found).associatedEntity
String type = associated instanceof RelationshipPersistentEntity ?
':' + ((RelationshipPersistentEntity) associated).type() : ''
return entity.formatAssociationPatternFromExisting((Association) found, type, variable, '')
}
null
}

/**
* The scope of the block of an association, whose pattern is matched into the query. The criteria of the
* block are about the associated entity, so a property is looked up there: a plain property of the same name as
* an association of the entity the query started from is still a plain property, and an association of the
* associated entity is tested as one. An association to a relationship entity is about the relationship, so its
* scope is the relationship entity, and its variable is recorded as a relationship.
*/
CriterionScope into(AssociationQuery block) {
String target = "m_${builder.getNextMatchNumber()}"
String secondTarget = "m_${builder.getNextMatchNumber() + 1}"
Existence block1 = blockScope(block, target, secondTarget)
builder.addMatch(block1.pattern)
block1.scope
}

/**
* The scope of the block of an association that is tested for where it stands, as a block in a disjunction is,
* with the pattern to look for. Nothing is added to the matches of the query: the variables are local to the test.
*/
Existence intoExistence(AssociationQuery block) {
blockScope(block, "e_${builder.nextLocalNumber()}", "e_${builder.nextLocalNumber()}")
}

private Existence blockScope(AssociationQuery block, String variable, String secondVariable) {
Association association = block.association
String target = variable
String relationship = ''
boolean viaRelationship = block.entity instanceof RelationshipPersistentEntity
if (viaRelationship) {
relationship = "$variable:${(block.entity as RelationshipPersistentEntity).type()}"
target = secondVariable
}
String pattern = entity.formatAssociationPatternFromExisting(association, relationship, this.variable, target)
if (viaRelationship) {
RelationshipPersistentEntity relationshipEntity = (RelationshipPersistentEntity) block.entity
builder.addRelationshipVariable(variable, relationshipEntity)
// the node that owns the block is the end its entity is the relationship's, unless it is the other way round
boolean incoming = entity.is(relationshipEntity.to.associatedEntity) && !entity.is(relationshipEntity.from.associatedEntity)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

links { from { eq('name', 'Alice') } } on a relationship whose ends are the same type filters the receiving node. Alice as the origin is missing. Use the direction of the association.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 6bb0d55. matchForRelationshipEntity treated the owner as the receiving end whenever the owner was the to type, even when it was also the from type, while CriterionScope.into computed the opposite. For a relationship between the same type they disagreed. The owner is now the receiving end only when it is to and not from, so a self-referential relationship is outgoing from from, like alice.knows. links { from { eq('name', 'Alice') } } now filters the origin. The matrix has self-referential from and to block cells.

Two existing IsNullAssociationSpec expectations encoded the old backwards direction (the bond test, and isNull/isNotNull('feuds')). I changed them to the direction of the association, and the new owners in the bond test are explicit (with-set, with-unset). Please check those two.

return new Existence(pattern, new CriterionScope(relationshipEntity, builder, variable,
incoming ? target : this.variable, incoming ? this.variable : target))
}
PersistentEntity associated = association.associatedEntity
GraphPersistentEntity nested = associated instanceof GraphPersistentEntity ? (GraphPersistentEntity) associated : entity
new Existence(pattern, new CriterionScope(nested, builder, variable))
}

/** A pattern to look for, and the scope of the criteria about what it finds. */
static final class Existence {
final String pattern
final CriterionScope scope

Existence(String pattern, CriterionScope scope) {
this.pattern = pattern
this.scope = scope
}
}
}
Loading