Merge pull request #7364 from FlorentinD/document-cypher-agg-label-properties-behaviour-23

 Improve cypher aggregation docs

Author: FlorentinD

doc-test-tools/src/main/java/org/neo4j/gds/doc/syntax/ProcedureSyntaxAutoChecker.java

@@ -166,6 +166,8 @@ private Consumer<StructuralNode> assertTableValues(
                     .getCells()
                     .get(0)) // Get the first column in the row --> corresponds to the return column names
                 .map(Cell::getText)
+                // remove any potential links in the names
+                .map(name -> name.replaceAll("<a.*\">|<\\/a>", ""))
                 // as java identifier cannot contain white spaces, remove anything after the first space such as footnote:
                 .map(name -> name.split("\\s+")[0])
                 .collect(Collectors.toList());
@@ -176,7 +178,7 @@ private Consumer<StructuralNode> assertTableValues(
         };
     }
 
-    private Iterable<String> extractDocResultFields(String syntaxCode) {
+    private static Iterable<String> extractDocResultFields(String syntaxCode) {
         var yield = syntaxCode.substring(syntaxCode.indexOf(YIELD_KEYWORD) + YIELD_KEYWORD.length()).trim();
         return Arrays.stream(yield.split(YIELD_FIELD_SEPARATOR))
             .map(yieldField -> yieldField.split(YIELD_NAME_DATA_TYPE_SEPARATOR)[0].trim())

doc-test-tools/src/test/java/org/neo4j/gds/doc/syntax/ProcedureSyntaxAutoCheckerTest.java

@@ -23,11 +23,14 @@
 import org.asciidoctor.OptionsBuilder;
 import org.asciidoctor.SafeMode;
 import org.assertj.core.api.SoftAssertions;
+import org.assertj.core.api.junit.jupiter.InjectSoftAssertions;
 import org.assertj.core.api.junit.jupiter.SoftAssertionsExtension;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.junit.jupiter.api.io.TempDir;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 
 import java.io.File;
 import java.net.URISyntaxException;
@@ -48,6 +51,9 @@ class ProcedureSyntaxAutoCheckerTest {
 
     private static final String newLine = System.lineSeparator();
 
+    @InjectSoftAssertions
+    private SoftAssertions softAssertions;
+
     @BeforeEach
     void setUp() {
         // By default we are forced to use relative path which we don't want.
@@ -57,18 +63,19 @@ void setUp() {
 
     }
 
-    @Test
-    void correctSyntaxSectionTest(SoftAssertions softAssertions) throws URISyntaxException {
+    @ParameterizedTest(name = "{0}")
+    @ValueSource(strings = {"include-with-syntax.adoc", "include-with-syntax-parameter-with-link.adoc"})
+    void correctSyntaxSectionTest(String positiveResource) throws URISyntaxException {
         try (var asciidoctor = createAsciidoctor(softAssertions)) {
-            var file = Paths.get(getClass().getClassLoader().getResource("include-with-syntax.adoc").toURI()).toFile();
+            var file = Paths.get(getClass().getClassLoader().getResource(positiveResource).toURI()).toFile();
             assertTrue(file.exists() && file.canRead());
 
             asciidoctor.convertFile(file, options);
         }
     }
 
     @Test
-    void shouldFailOnMissingResultsTable(SoftAssertions softAssertions) throws URISyntaxException {
+    void shouldFailOnMissingResultsTable() throws URISyntaxException {
         try (var asciidoctor = createAsciidoctor(softAssertions)) {
             var file = Paths
                 .get(getClass()
@@ -85,7 +92,7 @@ void shouldFailOnMissingResultsTable(SoftAssertions softAssertions) throws URISy
     }
 
     @Test
-    void shouldFailOnMoreThanOneResultsTable(SoftAssertions softAssertions) throws URISyntaxException {
+    void shouldFailOnMoreThanOneResultsTable() throws URISyntaxException {
         try (var asciidoctor = createAsciidoctor(softAssertions)) {
             var file = Paths
                 .get(getClass()
@@ -102,7 +109,7 @@ void shouldFailOnMoreThanOneResultsTable(SoftAssertions softAssertions) throws U
     }
 
     @Test
-    void shouldFailOnMissingCodeBlock(SoftAssertions softAssertions) throws URISyntaxException {
+    void shouldFailOnMissingCodeBlock() throws URISyntaxException {
         try (var asciidoctor = createAsciidoctor(softAssertions)) {
             var file = Paths
                 .get(getClass().getClassLoader().getResource("invalid-include-with-syntax-no-code-block.adoc").toURI())
@@ -116,7 +123,7 @@ void shouldFailOnMissingCodeBlock(SoftAssertions softAssertions) throws URISynta
     }
 
     @Test
-    void shouldFailOnMoreThanOneCodeBlock(SoftAssertions softAssertions) throws URISyntaxException {
+    void shouldFailOnMoreThanOneCodeBlock() throws URISyntaxException {
         try (var asciidoctor = createAsciidoctor(softAssertions)) {
             var file = Paths
                 .get(getClass()

doc-test-tools/src/test/resources/include-with-syntax-parameter-with-link.adoc

@@ -0,0 +1,42 @@
+[.include-with-stream]
+======
+.Run Louvain in stream mode on a named graph.
+[source, cypher, role=noplay]
+----
+CALL gds.louvain.stream(
+  graphName: String,
+  configuration: Map
+)
+YIELD
+  nodeId: Integer,
+  communityId: Integer,
+  intermediateCommunityIds: List of Integer
+----
+
+.Parameters
+[opts="header"]
+|===
+| Name
+| graphName footnote:vital[choose the name wisely]
+| <<configuration-table, configuration>>
+|===
+
+// This table is only here to make sure we will really pick the `.Results` one
+[[configuration-table]]
+.Algorithm specific configuration
+[opts="header",cols="1,1,1m,1,4"]
+|===
+| Name                       | Type     | Default | Optional | Description
+| relationshipWeightProperty | String   | null    | yes      | Relationship Weight.
+| seedProperty               | String   | n/a     | yes      | Seed Property.
+|===
+
+.Results
+[opts="header",cols="1,1,6"]
+|===
+| Name                      | Type      | Description
+| nodeId                    | Integer   | Node ID.
+| communityId               | Integer   | The community ID of the final level.
+| intermediateCommunityIds  | List of Integer | Community IDs for each level. `Null` if `includeIntermediateCommunities` is set to false.
+|===
+======

doc/modules/ROOT/pages/management-ops/projections/graph-project-cypher-aggregation.adoc

@@ -3,35 +3,44 @@
 :description: This section details projecting GDS graphs using `Cypher` aggregations.
 
 
+Using Cypher aggregations is a more flexible and expressive approach with diminished focus on performance compared to the xref:management-ops/projections/graph-project.adoc[native projections].
+Cypher aggregations are primarily recommended for the development phase (see xref:common-usage/index.adoc[Common usage]).
 
-A projected graph can be stored in the catalog under a user-defined name.
-Using that name, the graph can be referred to by any algorithm in the library.
-This allows multiple algorithms to use the same graph without having to project it on each algorithm run.
 
-Using Cypher aggregations is a more flexible and expressive approach with diminished focus on performance compared to the xref:management-ops/projections/graph-project.adoc[native projections].
-Cypher projections are primarily recommended for the development phase (see xref:common-usage/index.adoc[Common usage]).
+== Considerations
 
-[NOTE]
---
-There is also a way to generate a random graph, see xref:management-ops/projections/graph-generation.adoc[Graph Generation] documentation for more details.
---
+=== Lifecycle
 
 [NOTE]
 --
-The projected graph will reside in the catalog until:
+The projected graphs will reside in the catalog until either:
 
 - the graph is dropped using xref:graph-drop.adoc[gds.graph.drop]
 - the Neo4j database from which the graph was projected is stopped or dropped
 - the Neo4j database management system is stopped.
 --
 
 
+=== Node property support
+
+Cypher aggregations can only project a limited set of node property types from a Cypher query.
+The xref:management-ops/node-properties.adoc#node-properties-supported[Node Properties page] details which node property types are supported.
+Other types of node properties have to be transformed or encoded into one of the supported types in order to be projected using a Cypher aggregation.
+
+=== Selection of node properties and labels
+
+If a node occurs multiple times, the node properties and labels of the first occurrence will be used for the projection.
+This is important when a node can be a source node as well as a target node and their configuration differs.
+Relevant configuration options are `sourceNodeProperties`, `targetNodeProperties`, `sourceNodeLabels` and `targetNodeLabels`.
+
+
 [[graph-project-cypher-aggregation-syntax]]
 == Syntax
 
 A Cypher aggregation is used in a query as an aggregation over the relationships that are being projected.
 It takes three mandatory arguments: `graphName`, `sourceNode` and `targetNode`.
-In addition, the optional `sourceNodeProperties`, `targetNodeProperties`, and `relationshipProperties` parameters allows us to project properties.
+In addition, two optional parameters can be used to project node properties and labels (`nodesConfig`) or relationship properties and type (`relationshipConfig`).
+The optional `configuration` parameter can be used for general configuration of the projection such as `readConcurrency`.
 
 [.graph-project-cypher-aggregation-syntax]
 --
@@ -53,15 +62,35 @@ RETURN gds.alpha.graph.project(
 ----
 
 .Parameters
-[opts="header",cols="1,1,8"]
+[opts="header",cols="2,1,7"]
 |===
 | Name               | Optional | Description
 | graphName          | no       | The name under which the graph is stored in the catalog.
 | sourceNode         | no       | The source node of the relationship. Must not be null.
 | targetNode         | yes      | The target node of the relationship. The targetNode can be null (for example due to an `OPTIONAL MATCH`), in which case the source node is projected as an unconnected node.
-| nodesConfig        | yes      | Properties and Labels configuration for the source and target nodes.
-| relationshipConfig | yes      | Properties and Type configuration for the relationship.
-| configuration      | yes      | Additional parameters to configure the cypher aggregation projection.
+| <<graph-project-cypher-aggregation-syntax-nodesConfig, nodesConfig>>        | yes      | Properties and labels configuration for the source and target nodes.
+| <<graph-project-cypher-aggregation-syntax-relationshipConfig, relationshipConfig>> | yes      | Properties and type configuration for the relationship.
+| <<graph-project-cypher-aggregation-syntax-configuration, configuration>>      | yes      | Additional parameters to configure the projection.
+|===
+
+[[graph-project-cypher-aggregation-syntax-nodesConfig]]
+.Nodes configuration
+[opts="header",cols="1,1,1,4"]
+|===
+| Name                 | Type                     | Default | Description
+| sourceNodeProperties | Map                      | {}      | The properties of the source node.
+| targetNodeProperties | Map                      | {}      | The properties of the target node.
+| sourceNodeLabels     | List of String or String | []      | The label(s) of the source node.
+| targetNodeLabels     | List of String or String | []      | The label(s) of the source node.
+|===
+
+[[graph-project-cypher-aggregation-syntax-relationshipConfig]]
+.Relationship configuration
+[opts="header",cols="1,1,1,4"]
+|===
+| Name                 | Type          | Default | Description
+| properties           | Map           | {}      | The properties of the source node.
+| relationshipType     | String        | '*'     | The type of the relationship.
 |===
 
 [[graph-project-cypher-aggregation-syntax-configuration]]