Merge pull request #874 from neo4j-contrib/rc/5.5.0

Rc/5.5.0

Author: mariusconjeaud

Changelog

@@ -1,3 +1,8 @@
+Version 5.5.0 2025-06
+* Add traverse method which merges traverse_relations and fetch_relations and improves them
+* Deprecate traverse_relations and fetch_relations
+* Fix issue where WITH * is inserted in wrong places
+
 Version 5.4.5 2025-03
 * Add method unique_variables to force reuse of variables in traversals
 * Fix bug when filtering on relationship property

doc/requirements.txt

@@ -1,3 +1,3 @@
 sphinx_copybutton
-neo4j~=5.19.0
+neo4j~=5.28.1
 

doc/source/advanced_query_operations.rst

@@ -72,9 +72,9 @@ Here is a full example::
     await Coffee.nodes.fetch_relations("suppliers")
         .intermediate_transform(
             {
-                "coffee": "coffee",
-                "suppliers": NodeNameResolver("suppliers"),
-                "r": RelationNameResolver("suppliers"),
+                "coffee": {"source": "coffee"},
+                "suppliers": {"source": NodeNameResolver("suppliers")},
+                "r": {"source": RelationNameResolver("suppliers")},
                 "coffee": {"source": "coffee", "include_in_return": True}, # Only coffee will be returned
                 "suppliers": {"source": NodeNameResolver("suppliers")},
                 "r": {"source": RelationNameResolver("suppliers")},
@@ -146,3 +146,15 @@ In some cases though, it is not possible to set explicit aliases, for example wh
 .. note:: 
 
     When using the resolvers in combination with a traversal as in the example above, it will resolve the variable name of the last element in the traversal - the Species node for NodeNameResolver, and Coffee--Species relationship for RelationshipNameResolver.
+
+Another example is to reference the root node itself::
+
+    subquery = await Coffee.nodes.subquery(
+        Coffee.nodes.traverse_relations(suppliers="suppliers")
+        .intermediate_transform(
+            {"suppliers": {"source": "suppliers"}}, ordering=["suppliers.delivery_cost"]
+        )
+        .annotate(supps=Last(Collect("suppliers"))),
+        ["supps"],
+        [NodeNameResolver("self")], # This is the root Coffee node
+    )

doc/source/configuration.rst

@@ -32,7 +32,7 @@ Adjust driver configuration - these options are only available for this connecti
     config.MAX_TRANSACTION_RETRY_TIME = 30.0  # default
     config.RESOLVER = None  # default
     config.TRUST = neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES  # default
-    config.USER_AGENT = neomodel/v5.4.5  # default
+    config.USER_AGENT = neomodel/v5.5.0  # default
 
 Setting the database name, if different from the default one::
 

doc/source/getting_started.rst

@@ -261,10 +261,10 @@ Retrieving additional relations
 .. note::
 
    You can fetch one or more relations within the same call
-   to `.fetch_relations()` and you can mix optional and non-optional
+   to `.traverse()` and you can mix optional and non-optional
    relations, like::
 
-    Person.nodes.fetch_relations('city__country', Optional('country')).all()
+    Person.nodes.traverse('city__country', Path(value='country', optional=True)).all()
 
 .. note::
 
@@ -368,12 +368,12 @@ The example below will show you how you can mix and match query operations, as d
     full_nodeset = (
         await Student.nodes.filter(name__istartswith="m", lives_in__name="Eiffel Tower") # Combine filters
         .order_by("name")
-        .fetch_relations(
+        .traverse(
             "parents",
-            Optional("children__preferred_course"),
-        ) # Combine fetch_relations
+            Path(value="children__preferred_course", optional=True)
+        ) # Combine traversals
         .subquery(
-            Student.nodes.fetch_relations("courses") # Root variable student will be auto-injected here
+            Student.nodes.traverse("courses") # Root variable student will be auto-injected here
             .intermediate_transform(
                 {"rel": RelationNameResolver("courses")},
                 ordering=[

doc/source/traversal.rst

@@ -6,7 +6,9 @@ Path traversal
 
 Neo4j is about traversing the graph, which means leveraging nodes and relations between them. This section will show you how to traverse the graph using neomodel.
 
-We will cover two methods : `traverse_relations` and `fetch_relations`. Those two methods are *mutually exclusive*, so you cannot chain them.
+For this, the method to use is `traverse`.
+
+Note that until version 6, two other methods are available, but deprecated : `traverse_relations` and `fetch_relations`. Those two methods are *mutually exclusive*, so you cannot chain them.
 
 For the examples in this section, we will be using the following model::
 
@@ -27,6 +29,59 @@ For the examples in this section, we will be using the following model::
 Traverse relations
 ------------------
 
+The `traverse` allows you to define multiple, multi-hop traversals, optionally returning traversed elements.
+
+For example, to find all `Coffee` nodes that have a supplier, and retrieve the country of that supplier, you can do::
+
+    Coffee.nodes.traverse("suppliers__country").all()
+
+This will generate a Cypher MATCH clause which traverses `Coffee<--Supplier-->Country`, and by default will return all traversed nodes and relationships.
+
+This method allows you to define a more complex `Path` object, giving you more control over the traversal.
+
+You can specify which elements to return, like::
+
+    # Return only the traversed nodes, not the relationships
+    Coffee.nodes.traverse(Path(value="suppliers__country", include_rels_in_return=False))
+
+    # Return only the traversed relationships, not the nodes
+    Coffee.nodes.traverse(Path(value="suppliers__country", include_nodes_in_return=False))
+
+You can specify that your traversal should be optional, like::
+
+    # Return only the traversed nodes, not the relationships
+    Coffee.nodes.traverse(Path(value="suppliers__country", optional=True))
+
+You can also alias the path, so that you can reference it later in the query, like::
+
+    Coffee.nodes.traverse(Path(value="suppliers__country", alias="supplier_country"))
+
+The `Country` nodes matched will be made available for the rest of the query, with the variable name `country`. Note that this aliasing is optional. See :ref:`Advanced query operations` for examples of how to use this aliasing.
+
+.. note::
+
+    The `traverse` method can be used to traverse multiple paths, like::
+
+        Coffee.nodes.traverse('suppliers__country', 'pub__city').all()
+
+    This will generate a Cypher MATCH clause that traverses both paths `Coffee<--Supplier-->Country` and `Coffee<--Pub-->City`.
+
+.. note::
+
+    When using `include_rels_in_return=True` (default), any relationship that you traverse using this method **MUST have a model defined**, even if only the default StructuredRel, like::
+        
+        class Person(StructuredNode):
+            country = RelationshipTo(Country, 'IS_FROM', model=StructuredRel)
+
+    Otherwise, neomodel will not be able to determine which relationship model to resolve into, and will fail.
+
+Traverse relations (deprecated)
+-------------------------------
+
+.. deprecated:: 5.5.0
+
+    This method is set to disappear in version 6, use `traverse` instead.
+
 The `traverse_relations` method allows you to filter on the existence of more complex traversals. For example, to find all `Coffee` nodes that have a supplier, and retrieve the country of that supplier, you can do::
 
     Coffee.nodes.traverse_relations(country='suppliers__country').all()
@@ -43,8 +98,12 @@ The `Country` nodes matched will be made available for the rest of the query, wi
 
     This will generate a Cypher MATCH clause that enforces the existence of at least one path like `Coffee<--Supplier-->Country` and `Coffee<--Pub-->City`.
 
-Fetch relations
----------------
+Fetch relations (deprecated)
+----------------------------
+
+.. deprecated:: 5.5.0
+
+    This method is set to disappear in version 6, use `traverse` instead.
 
 The syntax for `fetch_relations` is similar to `traverse_relations`, except that the generated Cypher will return all traversed objects (nodes and relations)::
 
@@ -59,8 +118,12 @@ The syntax for `fetch_relations` is similar to `traverse_relations`, except that
 
     Otherwise, neomodel will not be able to determine which relationship model to resolve into, and will fail.
 
-Optional match
---------------
+Optional match (deprecated)
+---------------------------
+
+.. deprecated:: 5.5.50
+
+    This method is set to disappear in version 6, use `traverse` instead.
 
 With both `traverse_relations` and `fetch_relations`, you can force the use of an ``OPTIONAL MATCH`` statement using the following syntax::
 

neomodel/_version.py

@@ -1 +1 @@
-__version__ = "5.4.5"
+__version__ = "5.5.0"