Merge pull request #895 from neo4j-contrib/rc/5.5.1

Rc/5.5.1

Author: mariusconjeaud

.gitignore

@@ -1,6 +1,7 @@
 venv
 venv2
 venv3
+.venv
 build
 doc/build
 dist
@@ -21,4 +22,4 @@ pyvenv.cfg
 coverage_report/
 .coverage*
 .DS_STORE
-cov.xml
+cov.xml

Changelog

@@ -1,3 +1,9 @@
+Version 5.5.1 2025-09
+* Fix cardinality enforcement for RelationshipFrom. Many thanks to @billycalladine
+* Change order of WITH and CALL{} statements in generated Cypher (intermediate_transform & subquery)
+* Add py.typed file to enable support from mypy
+* Bump to neo4j 5.28.2, uniform version pinning for rust-ext
+
 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

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.5.0  # default
+    config.USER_AGENT = neomodel/v5.5.1  # default
 
 Setting the database name, if different from the default one::
 

doc/source/index.rst

@@ -77,6 +77,7 @@ Contents
    filtering_ordering
    traversal
    advanced_query_operations
+   semantic_indexes
    cypher
    transactions
    hooks

doc/source/schema_management.rst

@@ -46,38 +46,11 @@ Indexes
 The following indexes are supported:
 
 - ``index=True``: This will create the default Neo4j index on the property (currently RANGE).
-- ``fulltext_index=FulltextIndex()``: This will create a FULLTEXT index on the property. Only available for Neo4j version 5.16 or higher. With this one, you can define the following options:
-    - ``analyzer``: The analyzer to use. The default is ``standard-no-stop-words``.
-    - ``eventually_consistent``: Whether the index should be eventually consistent. The default is ``False``.
-  
-Please refer to the `Neo4j documentation <https://neo4j.com/docs/cypher-manual/current/indexes/semantic-indexes/full-text-indexes/#configuration-settings>`_. for more information on fulltext indexes.
-
-- ``vector_index=VectorIndex()``: This will create a VECTOR index on the property. Only available for Neo4j version 5.15 (node) and 5.18 (relationship) or higher. With this one, you can define the following options:
-    - ``dimensions``: The dimension of the vector. The default is 1536.
-    - ``similarity_function``: The similarity algorithm to use. The default is ``cosine``.
-
-Those indexes are available for both node- and relationship properties.
+- :ref:`Semantic Indexes`
 
 .. note:: 
     Yes, you can create multiple indexes of a different type on the same property. For example, a default index and a fulltext index.
 
-.. note:: 
-    For the semantic indexes (fulltext and vector), this allows you to create indexes, but searching those indexes require using Cypher queries.
-    This is because Cypher only supports querying those indexes through a specific procedure for now.
-
-Full example: ::
-
-    from neomodel import StructuredNode, StringProperty, FulltextIndex, VectorIndex
-    class VeryIndexedNode(StructuredNode):
-        name = StringProperty(
-            index=True,
-            fulltext_index=FulltextIndex(analyzer='english', eventually_consistent=True)
-        )
-        name_embedding = ArrayProperty(
-            FloatProperty(),
-            vector_index=VectorIndex(dimensions=512, similarity_function='euclidean')
-        )
-
 Constraints
 ===========
 
@@ -93,4 +66,4 @@ Extracting the schema from a database
 =====================================
 
 You can extract the schema from an existing database using the ``neomodel_inspect_database`` script (:ref:`inspect_database_doc`).
-This script will output the schema in the neomodel format, including indexes and constraints.
+This script will output the schema in the neomodel format, including indexes and constraints.

doc/source/semantic_indexes.rst

@@ -0,0 +1,89 @@
+.. _Semantic Indexes: 
+
+==================================
+Semantic Indexes
+==================================
+
+Full Text Index
+----------------
+From version x.x (version number tbc) neomodel provides a way to interact with neo4j `Full Text indexing <https://neo4j.com/docs/cypher-manual/current/indexes/semantic-indexes/full-text-indexes/>`_. 
+The Full Text Index can be be created for both node and relationship properties. Only available for Neo4j version 5.16 or higher.
+
+Defining a Full Text Index on a Property
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Within neomodel, indexing is a decision that is made at class definition time as the index needs to be built. A Full Text index is defined using :class:`~neomodel.properties.FulltextIndex`
+To define a property with a full text index we use the following symantics::
+    
+    StringProperty(fulltext_index=FulltextIndex(analyzer="standard-no-stop-words", eventually_consistent=False)
+
+Where,
+    - ``analyzer``: The analyzer to use. The default is ``standard-no-stop-words``.
+    - ``eventually_consistent``: Whether the index should be eventually consistent. The default is ``False``.
+
+The index must then be built, this occurs when the function :func:`~neomodel.sync_.core.install_all_labels` is run. 
+
+Please refer to the `Neo4j documentation <https://neo4j.com/docs/cypher-manual/current/indexes/semantic-indexes/full-text-indexes/#configuration-settings>`_ for more information on fulltext indexes.
+
+Querying a Full Text Index on a Property
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is not currently implemented as a native neomodel query type. If you would like this please submit a github issue highlighting your useage pattern
+
+Alternatively, whilst this has not bbeen implemetned yet you can still leverage `db.cypher_query` with the correct syntax to perform your required query.
+
+Vector Index 
+------------
+From version x.x (version number tbc) neomodel provides a way to interact with neo4j `vector indexing <https://neo4j.com/docs/cypher-manual/current/indexes/semantic-indexes/vector-indexes/>`_.
+
+The Vector Index can be created on both node and relationship properties. Only available for Neo4j version 5.15 (node) and 5.18 (relationship) or higher. 
+
+Defining a Vector Index on a Property 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Within neomodel, indexing is a decision that is made at class definition time as the index needs to be built. A vector index is defined using :class:`~neomodel.properties.VectorIndex`.
+To define a property with a vector index we use the following symantics::
+
+    ArrayProperty(base_property=FloatProperty(), vector_index=VectorIndex(dimensions=512, similarity_function="cosine")
+    
+Where,
+    - ``dimensions``: The dimension of the vector. The default is 1536.
+    - ``similarity_function``: The similarity algorithm to use. The default is ``cosine``.
+
+The index must then be built, this occurs when the function :func:`~neomodel.sync_.core.install_all_labels` is run
+
+The vector indexes will then have the name "vector_index_{node.__label__}_{propertyname_with_vector_index}".
+
+.. attention:: 
+   Neomodel creates a new vectorindex for each specified property, thus you cannot have two distinct properties being placed into the same index. 
+
+Querying a Vector Index on a Property 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Node Property
+^^^^^^^^^^^^^
+The following node vector index property::
+
+    class someNode(StructuredNode):
+        vector = ArrayProperty(base_property=FloatProperty(), vector_index=VectorIndex(dimensions=512, similarity_function="cosine")
+        name = StringProperty()
+
+Can be queried using :class:`~neomodel.sematic_filters.VectorFilter`. Such as::
+
+    from neomodel.semantic_filters import VectorFilter
+    result = someNode.nodes.filter(vector_filter=VectorFilter(topk=3, vector_attribute_name="vector")).all()
+
+Where the result will be a list of length topk of tuples having the form (someNode, score). 
+
+The :class:`~neomodel.semantic_filters.VectorFilter` can be used in conjunction with the normal filter types.
+
+.. attention:: 
+    If you use VectorFilter in conjunction with normal filter types, only nodes that fit the filters will return thus, you may get less than the topk specified.
+   Furthermore, all node filters **should** work with VectorFilter, relationship filters will also work but WILL NOT return the vector similiarty score alongside the relationship filter, instead the topk nodes and their appropriate relationships will be returned.
+
+RelationshipProperty
+^^^^^^^^^^^^^^^^^^^^
+Currently neomodel has not implemented an OGM method for querying vector indexes on relationships.
+If this is something that you like please submit a github issue requirements highlighting your usage pattern. 
+
+Alternatively, whilst this has not been implemented yet you can still leverage `db.cypher_query` with the correct syntax to perform your required query. 
+

neomodel/_version.py

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

neomodel/async_/cardinality.py

@@ -15,6 +15,12 @@ class AsyncZeroOrOne(AsyncRelationshipManager):
 
     description = "zero or one relationship"
 
+    async def _check_cardinality(self, node: "AsyncStructuredNode") -> None:
+        if await self.get_len():
+            raise AttemptedCardinalityViolation(
+                f"Node already has {self} can't connect more"
+            )
+
     async def single(self) -> Optional["AsyncStructuredNode"]:
         """
         Return the associated node.
@@ -44,10 +50,6 @@ async def connect(
         :type: dict
         :return: True / rel instance
         """
-        if await super().get_len():
-            raise AttemptedCardinalityViolation(
-                f"Node already has {self} can't connect more"
-            )
         return await super().connect(node, properties)
 
 
@@ -96,6 +98,10 @@ class AsyncOne(AsyncRelationshipManager):
 
     description = "one relationship"
 
+    async def _check_cardinality(self, node: "AsyncStructuredNode") -> None:
+        if await self.get_len():
+            raise AttemptedCardinalityViolation("Node already has one relationship")
+
     async def single(self) -> "AsyncStructuredNode":
         """
         Return the associated node.
@@ -139,6 +145,4 @@ async def connect(
         """
         if not hasattr(self.source, "element_id") or self.source.element_id is None:
             raise ValueError("Node has not been saved cannot connect!")
-        if await super().get_len():
-            raise AttemptedCardinalityViolation("Node already has one relationship")
         return await super().connect(node, properties)