Merge pull request #9982 from IoannisPanagiotas/hashgnn-write-mode

HashGNN Write mode

Author: IoannisPanagiotas

applications/algorithms/node-embeddings/src/main/java/org/neo4j/gds/applications/algorithms/embeddings/HashGnnWriteStep.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Neo4j is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+package org.neo4j.gds.applications.algorithms.embeddings;
+
+import org.neo4j.gds.api.Graph;
+import org.neo4j.gds.api.GraphStore;
+import org.neo4j.gds.api.ResultStore;
+import org.neo4j.gds.applications.algorithms.machinery.WriteStep;
+import org.neo4j.gds.applications.algorithms.machinery.WriteToDatabase;
+import org.neo4j.gds.applications.algorithms.metadata.NodePropertiesWritten;
+import org.neo4j.gds.core.utils.progress.JobId;
+import org.neo4j.gds.embeddings.hashgnn.HashGNNResult;
+import org.neo4j.gds.embeddings.hashgnn.HashGNNWriteConfig;
+
+import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.GraphSage;
+
+class HashGnnWriteStep implements WriteStep<HashGNNResult, NodePropertiesWritten> {
+    private final WriteToDatabase writeToDatabase;
+    private final HashGNNWriteConfig configuration;
+
+    HashGnnWriteStep(WriteToDatabase writeToDatabase, HashGNNWriteConfig configuration) {
+        this.writeToDatabase = writeToDatabase;
+        this.configuration = configuration;
+    }
+
+    @Override
+    public NodePropertiesWritten execute(
+        Graph graph,
+        GraphStore graphStore,
+        ResultStore resultStore,
+        HashGNNResult result,
+        JobId jobId
+    ) {
+        var nodePropertyValues = result.embeddings();
+
+        return writeToDatabase.perform(
+            graph,
+            graphStore,
+            resultStore,
+            configuration,
+            configuration,
+            GraphSage,
+            jobId,
+            nodePropertyValues
+        );
+    }
+}

applications/algorithms/node-embeddings/src/main/java/org/neo4j/gds/applications/algorithms/embeddings/NodeEmbeddingAlgorithmsWriteModeBusinessFacade.java

@@ -30,6 +30,8 @@
 import org.neo4j.gds.embeddings.fastrp.FastRPWriteConfig;
 import org.neo4j.gds.embeddings.graphsage.algo.GraphSageResult;
 import org.neo4j.gds.embeddings.graphsage.algo.GraphSageWriteConfig;
+import org.neo4j.gds.embeddings.hashgnn.HashGNNResult;
+import org.neo4j.gds.embeddings.hashgnn.HashGNNWriteConfig;
 import org.neo4j.gds.embeddings.node2vec.Node2VecResult;
 import org.neo4j.gds.embeddings.node2vec.Node2VecWriteConfig;
 import org.neo4j.gds.logging.Log;
@@ -39,6 +41,7 @@
 
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.FastRP;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.GraphSage;
+import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.HashGNN;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.Node2Vec;
 
 public final class NodeEmbeddingAlgorithmsWriteModeBusinessFacade {
@@ -120,6 +123,23 @@ public <RESULT> RESULT graphSage(
             resultBuilder
         );
     }
+    public <RESULT> RESULT hashGnn(
+        GraphName graphName,
+        HashGNNWriteConfig configuration,
+        ResultBuilder<HashGNNWriteConfig, HashGNNResult, RESULT, NodePropertiesWritten> resultBuilder
+    ) {
+        var writeStep = new HashGnnWriteStep(writeToDatabase, configuration);
+
+        return algorithmProcessingTemplateConvenience.processRegularAlgorithmInWriteMode(
+            graphName,
+            configuration,
+            HashGNN,
+            () -> estimationFacade.hashGnn(configuration),
+            (graph, __) -> algorithms.hashGnn(graph, configuration),
+            writeStep,
+            resultBuilder
+        );
+    }
 
     public <RESULT> RESULT node2Vec(
         GraphName graphName,

doc-test/src/test/java/org/neo4j/gds/doc/HashGNNDocTest.java

@@ -21,6 +21,7 @@
 
 import org.neo4j.gds.embeddings.hashgnn.HashGNNMutateProc;
 import org.neo4j.gds.embeddings.hashgnn.HashGNNStreamProc;
+import org.neo4j.gds.embeddings.hashgnn.HashGNNWriteProc;
 import org.neo4j.gds.functions.AsNodeFunc;
 import org.neo4j.gds.scaling.ScalePropertiesMutateProc;
 
@@ -33,6 +34,7 @@ protected List<Class<?>> procedures() {
         return List.of(
             HashGNNStreamProc.class,
             HashGNNMutateProc.class,
+            HashGNNWriteProc.class,
             ScalePropertiesMutateProc.class
         );
     }

doc/modules/ROOT/pages/machine-learning/node-embeddings/hashgnn.adoc

@@ -342,9 +342,48 @@ include::partial$/machine-learning/node-embeddings/hashgnn/specific-configuratio
 | configuration         | Map     | Configuration used for running the algorithm.
 |===
 ======
+[.include-with-write]
+======
 
-====
+.Run HashGNN in write mode on a named graph.
+[source, cypher, role=noplay]
+----
+CALL gds.hashgnn.write(
+  graphName: String,
+  configuration: Map
+) YIELD
+  nodeCount: Integer,
+  nodePropertiesWritten: Integer,
+  preProcessingMillis: Integer,
+  computeMillis: Integer,
+  writeMillis: Integer,
+  configuration: Map
+----
 
+include::partial$/algorithms/common-configuration/common-parameters.adoc[]
+
+.Configuration
+[opts="header",cols="3,2,3m,2,8"]
+|===
+| Name          | Type   | Default | Optional | Description
+include::partial$/algorithms/common-configuration/common-write-configuration-entries.adoc[]
+include::partial$/machine-learning/node-embeddings/hashgnn/specific-configuration.adoc[]
+|===
+
+.Results
+[opts="header"]
+|===
+| Name                  | Type    | Description
+| nodeCount             | Integer | Number of nodes processed.
+| nodePropertiesWritten | Integer | Number of node properties written.
+| preProcessingMillis   | Integer | Milliseconds for preprocessing the graph.
+| computeMillis         | Integer | Milliseconds for running the algorithm.
+| writeMillis          | Integer | Milliseconds for writing back results.
+| configuration         | Map     | Configuration used for running the algorithm.
+|===
+======
+
+====
 
 [[algorithms-embeddings-hashgnn-examples]]
 == Examples
@@ -702,6 +741,38 @@ YIELD nodePropertiesWritten
 The graph 'persons' now has a node property `hashgnn-embedding` which stores the node embedding for each node.
 To find out how to inspect the new schema of the in-memory graph, see xref:management-ops/graph-list.adoc[Listing graphs].
 
+[[algorithms-embeddings-hashgnn-examples-write]]
+=== Write
+
+include::partial$/algorithms/shared/examples-write-intro.adoc[]
+
+[role=query-example]
+--
+.The following will run the algorithm in `write` mode:
+[source, cypher, role=noplay]
+----
+CALL gds.hashgnn.write(
+  'persons',
+  {
+    writeProperty: 'hashgnn-embedding',
+    heterogeneous: true,
+    iterations: 2,
+    embeddingDensity: 4,
+    binarizeFeatures: {dimension: 6, threshold: 0.2},
+    featureProperties: ['experience_scaled', 'sourness', 'sweetness', 'tropical'],
+    randomSeed: 42
+  }
+)
+YIELD nodePropertiesWritten
+----
+
+[opts=header]
+.Results
+|===
+| nodePropertiesWritten
+| 11
+|===
+--
 
 [[algorithms-embeddings-hashgnn-virtual-example]]
 === Virtual example

doc/modules/ROOT/pages/operations-reference/algorithm-references.adoc

@@ -366,11 +366,13 @@
 | `gds.beta.graphSage.write.estimate` label:procedure[Procedure]
 | `gds.beta.graphSage.train` label:procedure[Procedure]
 | `gds.beta.graphSage.train.estimate` label:procedure[Procedure]
-.4+<.^|xref:machine-learning/node-embeddings/hashgnn.adoc[HashGNN]
+.6+<.^|xref:machine-learning/node-embeddings/hashgnn.adoc[HashGNN]
 | `gds.hashgnn.mutate` label:procedure[Procedure]
 | `gds.hashgnn.mutate.estimate` label:procedure[Procedure]
 | `gds.hashgnn.stream` label:procedure[Procedure]
 | `gds.hashgnn.stream.estimate` label:procedure[Procedure]
+| `gds.hashgnn.write` label:procedure[Procedure]
+| `gds.hashgnn.write.estimate` label:procedure[Procedure]
 .6+<.^|xref:machine-learning/node-embeddings/node2vec.adoc[Node2Vec]
 | `gds.node2vec.mutate` label:procedure[Procedure]
 | `gds.node2vec.mutate.estimate` label:procedure[Procedure]

open-packaging/src/test/java/org/neo4j/gds/OpenGdsProcedureSmokeTest.java

@@ -151,6 +151,8 @@ class OpenGdsProcedureSmokeTest extends BaseProcTest {
         "gds.hashgnn.mutate.estimate",
         "gds.hashgnn.stream",
         "gds.hashgnn.stream.estimate",
+        "gds.hashgnn.write",
+        "gds.hashgnn.write.estimate",
 
         "gds.beta.pipeline.linkPrediction.addFeature",
         "gds.beta.pipeline.linkPrediction.addNodeProperty",
@@ -600,7 +602,7 @@ void countShouldMatch() {
         );
 
         // If you find yourself updating this count, please also update the count in SmokeTest.kt
-        int expectedCount = 441;
+        int expectedCount = 443;
         assertEquals(
             expectedCount,
             returnedRows,

proc/embeddings/src/integrationTest/java/org/neo4j/gds/embeddings/hashgnn/HashGNNWriteProcTest.java

@@ -0,0 +1,116 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Neo4j is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+package org.neo4j.gds.embeddings.hashgnn;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.neo4j.gds.BaseProcTest;
+import org.neo4j.gds.GdsCypher;
+import org.neo4j.gds.catalog.GraphProjectProc;
+import org.neo4j.gds.extension.Neo4jGraph;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.InstanceOfAssertFactories.LONG;
+
+class HashGNNWriteProcTest extends BaseProcTest {
+
+    @Neo4jGraph
+    private static final String DB_CYPHER =
+        "CREATE" +
+        "  (a:N {f1: 1, f2: [0.0, 0.0]})" +
+        ", (b:N {f1: 0, f2: [1.0, 0.0]})" +
+        ", (c:N {f1: 0, f2: [0.0, 1.0]})" +
+        ", (b)-[:R1]->(a)" +
+        ", (b)-[:R2]->(c)";
+
+    static String expectedMutatedGraph = "CREATE" +
+                                         "  (a:N {f1: 1, f2: [0.0, 0.0], embedding: [1.0, 0.0, 0.0]})" +
+                                         ", (b:N {f1: 0, f2: [1.0, 0.0], embedding: [1.0, 0.0, 1.0]})" +
+                                         ", (c:N {f1: 0, f2: [0.0, 1.0], embedding: [0.0, 0.0, 1.0]})" +
+                                         ", (b)-[:R1]->(a)" +
+                                         ", (b)-[:R2]->(c)";
+
+    @BeforeEach
+    void setupGraph() throws Exception {
+        registerProcedures(
+            HashGNNWriteProc.class,
+            GraphProjectProc.class
+        );
+
+        String graphCreateQuery = GdsCypher.call("graph")
+            .graphProject()
+            .withNodeLabel("N")
+            .withNodeProperty("f1")
+            .withNodeProperty("f2")
+            .withRelationshipType("R1")
+            .withRelationshipType("R2")
+            .yields();
+        runQuery(graphCreateQuery);
+    }
+
+    @Test
+    void shouldWrite() {
+        var query = GdsCypher.call("graph").algo("hashgnn")
+            .writeMode().addParameter("heterogeneous", true)
+            .addParameter("iterations", 2)
+            .addParameter("embeddingDensity", 2)
+            .addParameter("randomSeed", 42L)
+            .addParameter("featureProperties", List.of("f1", "f2"))
+            .addParameter("writeProperty", "embedding")
+            .yields();
+
+        var rowCount = runQueryWithRowConsumer(query, row -> {
+            assertThat(row.getNumber("preProcessingMillis"))
+                .asInstanceOf(LONG)
+                .isGreaterThan(-1L);
+
+            assertThat(row.getNumber("computeMillis"))
+                .asInstanceOf(LONG)
+                .isGreaterThan(-1L);
+
+            assertThat(row.getNumber("writeMillis"))
+                .asInstanceOf(LONG)
+                .isGreaterThan(-1L);
+
+            assertThat(row.getNumber("nodePropertiesWritten"))
+                .asInstanceOf(LONG)
+                .isEqualTo(3L);
+
+            assertThat(row.getNumber("nodeCount"))
+                .asInstanceOf(LONG)
+                .isEqualTo(3L);
+
+            assertThat(row.get("configuration"))
+                .isInstanceOf(Map.class);
+        });
+
+        assertThat(rowCount).isEqualTo(1L);
+
+        var nodePropertiesWritten = runQueryWithRowConsumer("MATCH (n) RETURN size(n.embedding) AS size", row -> {
+            assertThat(row.getNumber("size")).asInstanceOf(LONG).isEqualTo(3L);
+        });
+
+        assertThat(nodePropertiesWritten).isEqualTo(3L);
+    }
+
+}