Merge pull request #687 from FlorentinD/sessions-disable-topological-lp

FlorentinD · web-flow · commit fafa2e54a058 · 2024-07-18T09:51:47.000+02:00
Sessions - disallow topological lp + support util functions
diff --git a/README.md b/README.md
@@ -98,8 +98,6 @@ The manual is versioned to cover all GDS Python Client versions, so make sure to
 Operations known to not yet work with `graphdatascience`:
 
 * [Numeric utility functions](https://neo4j.com/docs/graph-data-science/current/management-ops/utility-functions/#utility-functions-numeric) (will never be supported)
-* [Cypher on GDS](https://neo4j.com/docs/graph-data-science/current/management-ops/create-cypher-db/) (might be supported in the future)
-* [Projecting graphs using Cypher Aggregation](https://neo4j.com/docs/graph-data-science/current/management-ops/projections/graph-project-cypher-aggregation/) (might be supported in the future)
 
 
 ## License
diff --git a/doc/modules/ROOT/pages/gds-session.adoc b/doc/modules/ROOT/pages/gds-session.adoc
@@ -255,6 +255,11 @@ gds.graph.nodeProperties.stream(G, db_node_properties=["name"], node_properties=
 For a full list of the available algorithms, see the https://neo4j.com/docs/graph-data-science-client/{page-version}/api/[API reference].
 
 
+=== Limitations
+
+Topological Link Prediction algorithms are not yet supported.
+
+
 == Remote write-back
 
 The GDS Session's in-memory graph was projected from data in AuraDB, so write-back operations will persist the data back to the same AuraDB instance.
@@ -282,5 +287,3 @@ Therefore, you will not be able to call any GDS procedures from the `run_cypher(
 ----
 gds.run_cypher("MATCH (n:User) RETURN n.name, n.embedding")
 ----
-
-
diff --git a/doc/modules/ROOT/pages/tutorials/gds-sessions.adoc b/doc/modules/ROOT/pages/tutorials/gds-sessions.adoc
@@ -28,7 +28,7 @@ to have the `graphdatascience` Python library installed, version
 
 [source, python, role=no-test]
 ----
-%pip install --pre "graphdatascience>1.10"
+%pip install --pre "graphdatascience>1.11a3"
 ----
 
 == Aura API credentials
diff --git a/examples/gds-sessions.ipynb b/examples/gds-sessions.ipynb
@@ -55,7 +55,7 @@
    },
    "outputs": [],
    "source": [
-    "%pip install --pre \"graphdatascience>1.10\""
+    "%pip install --pre \"graphdatascience>1.11a3\""
    ]
   },
   {
diff --git a/graphdatascience/call_builder.py b/graphdatascience/call_builder.py
@@ -1,6 +1,6 @@
 from .algo.algo_endpoints import AlgoEndpoints
 from .error.uncallable_namespace import UncallableNamespace
-from .utils.util_endpoints import IndirectUtilAlphaEndpoints
+from .utils.direct_util_endpoints import IndirectUtilAlphaEndpoints
 
 
 class IndirectCallBuilder(AlgoEndpoints, UncallableNamespace):
diff --git a/graphdatascience/endpoints.py b/graphdatascience/endpoints.py
@@ -23,7 +23,7 @@
     SystemBetaEndpoints,
 )
 from .topological_lp.topological_lp_endpoints import TopologicalLPAlphaEndpoints
-from .utils.util_endpoints import DirectUtilEndpoints
+from .utils.direct_util_endpoints import DirectUtilEndpoints
 
 """
 This class should inherit endpoint classes that only contain endpoints that can be called directly from
@@ -44,7 +44,7 @@ def __init__(self, query_runner: QueryRunner, namespace: str, server_version: Se
 
 
 """
-This class should inherit endpoint classes that only expose calls of the `gds.beta` namespace.
+This class should inherit endpoint classes that only expose calls of the `gds.alpha` namespace.
 Example of such endpoints: "gds.alpha.listProgress".
 """
 
@@ -65,6 +65,21 @@ def __getattr__(self, attr: str) -> IndirectAlphaCallBuilder:
         return IndirectAlphaCallBuilder(self._query_runner, f"{self._namespace}.{attr}", self._server_version)
 
 
+class AlphaRemoteEndpoints(
+    GraphAlphaEndpoints,
+    PipelineAlphaEndpoints,
+    ModelAlphaEndpoints,
+    SingleModeAlphaAlgoEndpoints,
+    SystemAlphaEndpoints,
+    AlphaConfigEndpoints,
+):
+    def __init__(self, query_runner: QueryRunner, namespace: str, server_version: ServerVersion):
+        super().__init__(query_runner, namespace, server_version)
+
+    def __getattr__(self, attr: str) -> IndirectAlphaCallBuilder:
+        return IndirectAlphaCallBuilder(self._query_runner, f"{self._namespace}.{attr}", self._server_version)
+
+
 """
 This class should inherit endpoint classes that only expose calls of the `gds.beta` namespace.
 Example of such endpoints:  "gds.beta.listProgress".
diff --git a/graphdatascience/graph_data_science.py b/graphdatascience/graph_data_science.py
@@ -13,6 +13,7 @@
 from .query_runner.query_runner import QueryRunner
 from .server_version.server_version import ServerVersion
 from graphdatascience.graph.graph_proc_runner import GraphProcRunner
+from graphdatascience.utils.util_proc_runner import UtilProcRunner
 
 
 class GraphDataScience(DirectEndpoints, UncallableNamespace):
@@ -81,12 +82,16 @@ def __init__(
                 None if arrow is True else arrow,
             )
 
-        super().__init__(self._query_runner, "gds", self._server_version)
+        super().__init__(self._query_runner, namespace="gds", server_version=self._server_version)
 
     @property
     def graph(self) -> GraphProcRunner:
         return GraphProcRunner(self._query_runner, f"{self._namespace}.graph", self._server_version)
 
+    @property
+    def util(self) -> UtilProcRunner:
+        return UtilProcRunner(self._query_runner, f"{self._namespace}.util", self._server_version)
+
     @property
     def alpha(self) -> AlphaEndpoints:
         return AlphaEndpoints(self._query_runner, "gds.alpha", self._server_version)
diff --git a/graphdatascience/query_runner/arrow_query_runner.py b/graphdatascience/query_runner/arrow_query_runner.py
@@ -64,6 +64,9 @@ def run_cypher(
     ) -> DataFrame:
         return self._fallback_query_runner.run_cypher(query, params, database, custom_error)
 
+    def call_function(self, endpoint: str, params: Optional[CallParameters] = None) -> Any:
+        return self._fallback_query_runner.call_function(endpoint, params)
+
     def call_procedure(
         self,
         endpoint: str,
diff --git a/graphdatascience/query_runner/aura_db_query_runner.py b/graphdatascience/query_runner/aura_db_query_runner.py
@@ -35,6 +35,9 @@ def run_cypher(
     ) -> DataFrame:
         return self._db_query_runner.run_cypher(query, params, database, custom_error)
 
+    def call_function(self, endpoint: str, params: Optional[CallParameters] = None) -> Any:
+        return self._gds_query_runner.call_function(endpoint, params)
+
     def call_procedure(
         self,
         endpoint: str,
diff --git a/graphdatascience/query_runner/neo4j_query_runner.py b/graphdatascience/query_runner/neo4j_query_runner.py
@@ -131,6 +131,13 @@ def run_cypher(
 
             return df
 
+    def call_function(self, endpoint: str, params: Optional[CallParameters] = None) -> Any:
+        if params is None:
+            params = CallParameters()
+        query = f"RETURN {endpoint}({params.placeholder_str()})"
+
+        return self.run_cypher(query, params).squeeze()
+
     def call_procedure(
         self,
         endpoint: str,
diff --git a/graphdatascience/query_runner/query_runner.py b/graphdatascience/query_runner/query_runner.py
@@ -21,6 +21,10 @@ def call_procedure(
     ) -> DataFrame:
         pass
 
+    @abstractmethod
+    def call_function(self, endpoint: str, params: Optional[CallParameters] = None) -> Any:
+        pass
+
     @abstractmethod
     def run_cypher(
         self,
diff --git a/graphdatascience/session/aura_graph_data_science.py b/graphdatascience/session/aura_graph_data_science.py
@@ -3,7 +3,11 @@
 from pandas import DataFrame
 
 from graphdatascience.call_builder import IndirectCallBuilder
-from graphdatascience.endpoints import AlphaEndpoints, BetaEndpoints, DirectEndpoints
+from graphdatascience.endpoints import (
+    AlphaRemoteEndpoints,
+    BetaEndpoints,
+    DirectEndpoints,
+)
 from graphdatascience.error.uncallable_namespace import UncallableNamespace
 from graphdatascience.graph.graph_remote_proc_runner import GraphRemoteProcRunner
 from graphdatascience.query_runner.arrow_query_runner import ArrowQueryRunner
@@ -12,6 +16,7 @@
 from graphdatascience.query_runner.neo4j_query_runner import Neo4jQueryRunner
 from graphdatascience.server_version.server_version import ServerVersion
 from graphdatascience.session.dbms_connection_info import DbmsConnectionInfo
+from graphdatascience.utils.util_remote_proc_runner import UtilRemoteProcRunner
 
 
 class AuraGraphDataScience(DirectEndpoints, UncallableNamespace):
@@ -75,7 +80,7 @@ def __init__(
 
         self._delete_fn = delete_fn
 
-        super().__init__(self._query_runner, "gds", self._server_version)
+        super().__init__(self._query_runner, namespace="gds", server_version=self._server_version)
 
     def run_cypher(
         self, query: str, params: Optional[Dict[str, Any]] = None, database: Optional[str] = None
@@ -103,8 +108,12 @@ def graph(self) -> GraphRemoteProcRunner:
         return GraphRemoteProcRunner(self._query_runner, f"{self._namespace}.graph", self._server_version)
 
     @property
-    def alpha(self) -> AlphaEndpoints:
-        return AlphaEndpoints(self._query_runner, "gds.alpha", self._server_version)
+    def util(self) -> UtilRemoteProcRunner:
+        return UtilRemoteProcRunner(self._query_runner, f"{self._namespace}.util", self._server_version)
+
+    @property
+    def alpha(self) -> AlphaRemoteEndpoints:
+        return AlphaRemoteEndpoints(self._query_runner, "gds.alpha", self._server_version)
 
     @property
     def beta(self) -> BetaEndpoints:
diff --git a/graphdatascience/tests/integration/test_remote_util_ops.py b/graphdatascience/tests/integration/test_remote_util_ops.py
@@ -0,0 +1,77 @@
+from typing import Generator
+
+import pytest
+
+from graphdatascience.graph.graph_object import Graph
+from graphdatascience.server_version.server_version import ServerVersion
+from graphdatascience.session.aura_graph_data_science import AuraGraphDataScience
+
+
+@pytest.fixture(autouse=True)
+def G(gds_with_cloud_setup: AuraGraphDataScience) -> Generator[Graph, None, None]:
+    gds_with_cloud_setup.run_cypher(
+        """
+        CREATE
+        (a:Location {name: 'A', population: 1337}),
+        (b:Location {name: 'B'}),
+        (c:Location {name: 'C'}),
+        (d:Location {name: 'D'}),
+        (e:Location {name: 'G'}),
+        (f:Location {name: 2}),
+        (a)-[:ROAD {cost: 50}]->(b),
+        (a)-[:ROAD {cost: 50}]->(c),
+        (a)-[:ROAD {cost: 100}]->(d),
+        (b)-[:ROAD {cost: 40}]->(d),
+        (c)-[:ROAD {cost: 40}]->(d),
+        (c)-[:ROAD {cost: 80}]->(e),
+        (d)-[:ROAD {cost: 30}]->(e),
+        (d)-[:ROAD {cost: 80}]->(f),
+        (e)-[:ROAD {cost: 40}]->(f)
+        """
+    )
+    G, _ = gds_with_cloud_setup.graph.project(
+        "g",
+        """
+         MATCH (n)-[r]->(m)
+         RETURN gds.graph.project.remote(n, m, {
+            sourceNodeLabels: labels(n),
+            targetNodeLabels: labels(m),
+            sourceNodeProperties: n {.population},
+            targetNodeProperties: m {.population},
+            relationshipType: type(r),
+            relationshipProperties: properties(r)
+        })
+        """,
+    )
+
+    yield G
+
+    G.drop()
+    gds_with_cloud_setup.run_cypher("MATCH (n) DETACH DELETE n")
+
+
+@pytest.mark.cloud_architecture
+@pytest.mark.compatible_with(min_inclusive=ServerVersion(2, 7, 0))
+def test_remote_util_as_node(gds_with_cloud_setup: AuraGraphDataScience) -> None:
+    id = gds_with_cloud_setup.find_node_id(["Location"], {"name": "A"})
+    result = gds_with_cloud_setup.util.asNode(id)
+    assert result["name"] == "A"
+
+
+@pytest.mark.cloud_architecture
+@pytest.mark.compatible_with(min_inclusive=ServerVersion(2, 7, 0))
+def test_remote_util_as_nodes(gds_with_cloud_setup: AuraGraphDataScience) -> None:
+    ids = [
+        gds_with_cloud_setup.find_node_id(["Location"], {"name": "A"}),
+        gds_with_cloud_setup.find_node_id(["Location"], {"name": 2}),
+    ]
+    result = gds_with_cloud_setup.util.asNodes(ids)
+    assert len(result) == 2
+
+
+@pytest.mark.cloud_architecture
+@pytest.mark.compatible_with(min_inclusive=ServerVersion(2, 7, 0))
+def test_util_nodeProperty(gds_with_cloud_setup: AuraGraphDataScience, G: Graph) -> None:
+    id = gds_with_cloud_setup.find_node_id(["Location"], {"name": "A"})
+    result = gds_with_cloud_setup.util.nodeProperty(G, id, "population")
+    assert result == 1337
diff --git a/graphdatascience/tests/integration/test_util_ops.py b/graphdatascience/tests/integration/test_util_ops.py
@@ -9,8 +9,8 @@
 
 
 @pytest.fixture(autouse=True)
-def G(runner: Neo4jQueryRunner, gds: GraphDataScience) -> Generator[Graph, None, None]:
-    runner.run_cypher(
+def G(gds: GraphDataScience) -> Generator[Graph, None, None]:
+    gds.run_cypher(
         """
         CREATE
         (a:Location {name: 'A', population: 1337}),
@@ -39,7 +39,7 @@ def G(runner: Neo4jQueryRunner, gds: GraphDataScience) -> Generator[Graph, None,
     yield G
 
     G.drop()
-    runner.run_cypher("MATCH (n) DETACH DELETE n")
+    gds.run_cypher("MATCH (n) DETACH DELETE n")
 
 
 def test_find_node_id(runner: Neo4jQueryRunner, gds: GraphDataScience) -> None:
@@ -97,15 +97,6 @@ def test_util_asNode(gds: GraphDataScience) -> None:
     assert result["name"] == "A"
 
 
-def test_util_asNodes(gds: GraphDataScience) -> None:
-    ids = [
-        gds.find_node_id(["Location"], {"name": "A"}),
-        gds.find_node_id(["Location"], {"name": 2}),
-    ]
-    result = gds.util.asNodes(ids)
-    assert len(result) == 2
-
-
 def test_util_nodeProperty(gds: GraphDataScience, G: Graph) -> None:
     id = gds.find_node_id(["Location"], {"name": "A"})
     result = gds.util.nodeProperty(G, id, "population")
diff --git a/graphdatascience/tests/unit/conftest.py b/graphdatascience/tests/unit/conftest.py
@@ -44,6 +44,13 @@ def call_procedure(
 
         return self.run_cypher(query, params, database, custom_error)
 
+    def call_function(self, endpoint: str, params: Optional[CallParameters] = None) -> Any:
+        if params is None:
+            params = CallParameters()
+        query = f"RETURN {endpoint}({params.placeholder_str()})"
+
+        return self.run_cypher(query, params).squeeze()
+
     def run_cypher(
         self, query: str, params: Optional[Dict[str, Any]] = None, db: Optional[str] = None, custom_error: bool = True
     ) -> DataFrame:
diff --git a/graphdatascience/tests/unit/test_util_ops.py b/graphdatascience/tests/unit/test_util_ops.py
@@ -1,4 +1,6 @@
+from graphdatascience.graph.graph_object import Graph
 from graphdatascience.graph_data_science import GraphDataScience
+from graphdatascience.session.aura_graph_data_science import AuraGraphDataScience
 from graphdatascience.tests.unit.conftest import CollectingQueryRunner
 
 
@@ -11,3 +13,55 @@ def test_list(runner: CollectingQueryRunner, gds: GraphDataScience) -> None:
 
     assert runner.last_query() == "CALL gds.list()"
     assert runner.last_params() == {}
+
+
+def test_as_node(runner: CollectingQueryRunner, gds: GraphDataScience) -> None:
+    gds.util.asNode(1)
+
+    assert runner.last_query() == "RETURN gds.util.asNode(1) AS node"
+
+
+def test_remote_as_node(runner: CollectingQueryRunner, aura_gds: AuraGraphDataScience) -> None:
+    aura_gds.util.asNode(1)
+
+    assert runner.last_query() == "MATCH (n) WHERE id(n) = $nodeId RETURN n"
+    assert runner.last_params() == {"nodeId": 1}
+
+
+def test_as_nodes(runner: CollectingQueryRunner, gds: GraphDataScience) -> None:
+    gds.util.asNodes([1, 2, 3])
+
+    assert runner.last_query() == "RETURN gds.util.asNodes([1, 2, 3]) AS nodes"
+
+
+def test_remote_as_nodes(runner: CollectingQueryRunner, aura_gds: AuraGraphDataScience) -> None:
+    aura_gds.util.asNodes([1, 2, 3])
+
+    assert runner.last_query() == "MATCH (n) WHERE id(n) IN $nodeIds RETURN collect(n)"
+    assert runner.last_params() == {"nodeIds": [1, 2, 3]}
+
+
+def test_node_property(runner: CollectingQueryRunner, gds: GraphDataScience) -> None:
+    G = Graph("g", runner, gds._server_version)
+    gds.util.nodeProperty(G, 1, "my_prop", "my_label")
+
+    assert runner.last_query() == "RETURN gds.util.nodeProperty($graph_name, $node_id, $property_key, $node_label)"
+    assert runner.last_params() == {
+        "graph_name": "g",
+        "node_id": 1,
+        "property_key": "my_prop",
+        "node_label": "my_label",
+    }
+
+
+def test_remote_node_property(runner: CollectingQueryRunner, aura_gds: AuraGraphDataScience) -> None:
+    G = Graph("g", runner, aura_gds._server_version)
+    aura_gds.util.nodeProperty(G, 1, "my_prop", "my_label")
+
+    assert runner.last_query() == "RETURN gds.util.nodeProperty($graph_name, $node_id, $property_key, $node_label)"
+    assert runner.last_params() == {
+        "graph_name": "g",
+        "node_id": 1,
+        "property_key": "my_prop",
+        "node_label": "my_label",
+    }
diff --git a/graphdatascience/utils/direct_util_endpoints.py b/graphdatascience/utils/direct_util_endpoints.py
diff --git a/graphdatascience/utils/util_node_property_func_runner.py b/graphdatascience/utils/util_node_property_func_runner.py
diff --git a/graphdatascience/utils/util_proc_runner.py b/graphdatascience/utils/util_proc_runner.py
diff --git a/graphdatascience/utils/util_remote_proc_runner.py b/graphdatascience/utils/util_remote_proc_runner.py

Original file line number	Diff line number	Diff line change
`@@ -55,7 +55,7 @@`
`55`	`55`	`},`
`56`	`56`	`"outputs": [],`
`57`	`57`	`"source": [`
`58`		`- "%pip install --pre \"graphdatascience>1.10\""`
	`58`	`+ "%pip install --pre \"graphdatascience>1.11a3\""`
`59`	`59`	`]`
`60`	`60`	`},`
`61`	`61`	`{`