[NOID] Procedure argument descriptions (#664)

Author: gem-neo4j

common/src/main/java/apoc/cypher/CypherUtils.java

@@ -22,7 +22,7 @@
 import static java.lang.String.join;
 import static java.util.stream.Collectors.toList;
 
-import apoc.result.MapResult;
+import apoc.result.CypherStatementMapResult;
 import java.util.Collection;
 import java.util.Collections;
 import java.util.Map;
@@ -31,11 +31,11 @@
 import org.neo4j.procedure.Name;
 
 public class CypherUtils {
-    public static Stream<MapResult> runCypherQuery(
+    public static Stream<CypherStatementMapResult> runCypherQuery(
             Transaction tx, @Name("cypher") String statement, @Name("params") Map<String, Object> params) {
         if (params == null) params = Collections.emptyMap();
         return tx.execute(withParamMapping(statement, params.keySet()), params).stream()
-                .map(MapResult::new);
+                .map(CypherStatementMapResult::new);
     }
 
     public static String withParamMapping(String fragment, Collection<String> keys) {

common/src/main/java/apoc/export/util/ExportUtils.java

@@ -19,7 +19,7 @@
 package apoc.export.util;
 
 import apoc.export.cypher.ExportFileManager;
-import apoc.result.ProgressInfo;
+import apoc.result.ExportProgressInfo;
 import apoc.util.QueueBasedSpliterator;
 import apoc.util.QueueUtil;
 import apoc.util.Util;
@@ -34,7 +34,7 @@
 public class ExportUtils {
     private ExportUtils() {}
 
-    public static Stream<ProgressInfo> getProgressInfoStream(
+    public static Stream<ExportProgressInfo> getProgressInfoStream(
             GraphDatabaseService db,
             ExecutorService executorService,
             TerminationGuard terminationGuard,
@@ -44,12 +44,13 @@ public static Stream<ProgressInfo> getProgressInfoStream(
             ExportFileManager cypherFileManager,
             Consumer<ProgressReporter> dump) {
         long timeout = exportConfig.getTimeoutSeconds();
-        final ArrayBlockingQueue<ProgressInfo> queue = new ArrayBlockingQueue<>(1000);
+        final ArrayBlockingQueue<ExportProgressInfo> queue = new ArrayBlockingQueue<>(1000);
         ProgressReporter reporterWithConsumer = reporter.withConsumer((pi) -> QueueUtil.put(
                 queue,
-                pi == ProgressInfo.EMPTY
-                        ? ProgressInfo.EMPTY
-                        : new ProgressInfo(pi).drain(cypherFileManager.getStringWriter(format), exportConfig),
+                pi == ExportProgressInfo.EMPTY
+                        ? ExportProgressInfo.EMPTY
+                        : new ExportProgressInfo((ExportProgressInfo) pi)
+                                .drain(cypherFileManager.getStringWriter(format), exportConfig),
                 timeout));
         Util.inTxFuture(
                 null,
@@ -61,9 +62,9 @@ public static Stream<ProgressInfo> getProgressInfoStream(
                 },
                 0,
                 _ignored -> {},
-                _ignored -> QueueUtil.put(queue, ProgressInfo.EMPTY, timeout));
-        QueueBasedSpliterator<ProgressInfo> spliterator =
-                new QueueBasedSpliterator<>(queue, ProgressInfo.EMPTY, terminationGuard, (int) timeout);
+                _ignored -> QueueUtil.put(queue, ExportProgressInfo.EMPTY, timeout));
+        QueueBasedSpliterator<ExportProgressInfo> spliterator =
+                new QueueBasedSpliterator<>(queue, ExportProgressInfo.EMPTY, terminationGuard, (int) timeout);
         return StreamSupport.stream(spliterator, false);
     }
 }

common/src/main/java/apoc/export/util/ProgressReporter.java

@@ -23,10 +23,6 @@
 import java.util.function.Consumer;
 import java.util.stream.Stream;
 
-/**
- * @author mh
- * @since 22.05.16
- */
 public class ProgressReporter implements Reporter {
     private final SizeCounter sizeCounter;
     private final PrintWriter out;
@@ -44,7 +40,7 @@ public ProgressReporter(SizeCounter sizeCounter, PrintWriter out, ProgressInfo p
         this.out = out;
         this.time = start;
         this.progressInfo = progressInfo;
-        this.batchSize = progressInfo.batchSize;
+        this.batchSize = progressInfo.getBatchSize();
     }
 
     public ProgressReporter withConsumer(Consumer<ProgressInfo> consumer) {
@@ -92,8 +88,8 @@ public void acceptBatch() {
 
     public void updateRunningBatch(ProgressInfo progressInfo) {
         lastBatch = Math.max(totalEntities / batchSize, lastBatch);
-        progressInfo.batches = lastBatch;
-        this.progressInfo.rows = totalEntities;
+        progressInfo.setBatches(lastBatch);
+        this.progressInfo.setRows(totalEntities);
         this.progressInfo.updateTime(start);
     }
 

common/src/main/java/apoc/get/Get.java

@@ -18,8 +18,11 @@
  */
 package apoc.get;
 
+import apoc.result.CreatedNodeResult;
 import apoc.result.NodeResult;
 import apoc.result.RelationshipResult;
+import apoc.result.UpdatedNodeResult;
+import apoc.result.UpdatedRelationshipResult;
 import apoc.util.Util;
 import java.util.stream.Stream;
 import org.neo4j.kernel.impl.coreapi.InternalTransaction;
@@ -37,7 +40,19 @@ public Stream<NodeResult> nodes(@Name("nodes") Object ids) {
         return Util.nodeStream(tx, ids).map(NodeResult::new);
     }
 
+    public Stream<UpdatedNodeResult> updatedNodes(@Name("nodes") Object ids) {
+        return Util.nodeStream(tx, ids).map(UpdatedNodeResult::new);
+    }
+
+    public Stream<CreatedNodeResult> createdNodes(@Name("nodes") Object ids) {
+        return Util.nodeStream(tx, ids).map(CreatedNodeResult::new);
+    }
+
     public Stream<RelationshipResult> rels(@Name("rels") Object ids) {
         return Util.relsStream(tx, ids).map(RelationshipResult::new);
     }
+
+    public Stream<UpdatedRelationshipResult> updatesRels(@Name("rels") Object ids) {
+        return Util.relsStream(tx, ids).map(UpdatedRelationshipResult::new);
+    }
 }

common/src/main/java/apoc/load/LoadJsonUtils.java

@@ -18,7 +18,7 @@
  */
 package apoc.load;
 
-import apoc.result.MapResult;
+import apoc.result.LoadDataMapResult;
 import apoc.util.JsonUtil;
 import apoc.util.Util;
 import java.util.Collections;
@@ -31,7 +31,7 @@
 import org.neo4j.procedure.TerminationGuard;
 
 public class LoadJsonUtils {
-    public static Stream<MapResult> loadJsonStream(
+    public static Stream<LoadDataMapResult> loadJsonStream(
             @Name("urlOrKeyOrBinary") Object urlOrKeyOrBinary,
             @Name("headers") Map<String, Object> headers,
             @Name("payload") String payload,
@@ -52,7 +52,7 @@ public static Stream<MapResult> loadJsonStream(
                 terminationGuard.check();
             }
             if (value instanceof Map) {
-                return Stream.of(new MapResult((Map) value));
+                return Stream.of(new LoadDataMapResult((Map) value));
             }
             if (value instanceof List) {
                 if (((List) value).isEmpty()) return Stream.empty();
@@ -61,13 +61,13 @@ public static Stream<MapResult> loadJsonStream(
                         if (terminationGuard != null) {
                             terminationGuard.check();
                         }
-                        return new MapResult((Map) v);
+                        return new LoadDataMapResult((Map) v);
                     });
-                return Stream.of(new MapResult(Collections.singletonMap("result", value)));
+                return Stream.of(new LoadDataMapResult(Collections.singletonMap("result", value)));
             }
             if (!failOnError)
                 throw new RuntimeException("Incompatible Type " + (value == null ? "null" : value.getClass()));
-            else return Stream.of(new MapResult(Collections.emptyMap()));
+            else return Stream.of(new LoadDataMapResult(Collections.emptyMap()));
         });
     }
 }

common/src/main/java/apoc/meta/Tables4LabelsProfile.java

@@ -26,6 +26,7 @@
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
 import org.neo4j.graphdb.*;
+import org.neo4j.procedure.Description;
 
 public class Tables4LabelsProfile {
     Map<OrderedLabels, PropertyContainerProfile> labelMap;
@@ -37,12 +38,25 @@ public class Tables4LabelsProfile {
      * DAO class that the stored procedure returns
      */
     public class NodeTypePropertiesEntry {
+        @Description("The type of the node.")
         public String nodeType;
+
+        @Description("The labels on the node.")
         public List<String> nodeLabels;
+
+        @Description("The name of the property.")
         public String propertyName;
+
+        @Description("The types this property has.")
         public List<String> propertyTypes;
+
+        @Description("Whether or not this property exists on all nodes of the given type.")
         public boolean mandatory;
+
+        @Description("The number of times this property was observed.")
         public long propertyObservations;
+
+        @Description("The number of times the label was seen.")
         public long totalObservations;
 
         public NodeTypePropertiesEntry(
@@ -64,13 +78,28 @@ public NodeTypePropertiesEntry(
     }
 
     public class RelTypePropertiesEntry {
+        @Description("The type of the relationship.")
         public String relType;
+
+        @Description("The labels belonging to the start node.")
         public List<String> sourceNodeLabels;
+
+        @Description("The labels belonging to the end node.")
         public List<String> targetNodeLabels;
+
+        @Description("The name of the property.")
         public String propertyName;
+
+        @Description("The types this property has.")
         public List<String> propertyTypes;
+
+        @Description("Whether or not this property exists on all nodes of the given type.")
         public boolean mandatory;
+
+        @Description("The number of times this property was observed.")
         public long propertyObservations;
+
+        @Description("The number of times the label was seen.")
         public long totalObservations;
 
         public RelTypePropertiesEntry(

common/src/main/java/apoc/periodic/BatchAndTotalResult.java

@@ -21,20 +21,74 @@
 import apoc.util.Util;
 import java.util.List;
 import java.util.Map;
+import org.neo4j.procedure.Description;
 
 public class BatchAndTotalResult {
+    @Description("The total number of batches.")
     public final long batches;
+
+    @Description("The number of processed input rows.")
     public final long total;
+
+    @Description("The duration taken in seconds.")
     public final long timeTaken;
+
+    @Description("The number of successful inner queries (actions).")
     public final long committedOperations;
+
+    @Description("The number of failed inner queries (actions).")
     public final long failedOperations;
+
+    @Description("The number of failed batches.")
     public final long failedBatches;
+
+    @Description("The number of retries.")
     public final long retries;
+
+    @Description("A map of batch error messages paired with their corresponding error counts.")
     public final Map<String, Long> errorMessages;
+
+    @Description(
+            """
+            {
+                 total :: INTEGER,
+                 failed :: INTEGER,
+                 committed :: INTEGER,
+                 errors :: MAP
+            }
+            """)
     public final Map<String, Object> batch;
+
+    @Description(
+            """
+            {
+                 total :: INTEGER,
+                 failed :: INTEGER,
+                 committed :: INTEGER,
+                 errors :: MAP
+            }
+            """)
     public final Map<String, Object> operations;
+
+    @Description("If the transaction was terminated before completion.")
     public final boolean wasTerminated;
+
+    @Description(
+            "Parameters of failed batches. The key is the batch number as a STRING and the value is a list of batch parameters.")
     public final Map<String, List<Map<String, Object>>> failedParams;
+
+    @Description(
+            """
+            {
+                nodesCreated :: INTEGER,
+                nodesDeleted :: INTEGER,
+                relationshipsCreated :: INTEGER,
+                relationshipsDeleted :: INTEGER,
+                propertiesSet :: INTEGER,
+                labelsAdded :: INTEGER,
+                labelsRemoved :: INTEGER
+            }
+            """)
     public final Map<String, Long> updateStatistics;
 
     public BatchAndTotalResult(

common/src/main/java/apoc/periodic/PeriodicUtils.java

@@ -45,17 +45,27 @@
 import org.neo4j.graphdb.Result;
 import org.neo4j.graphdb.Transaction;
 import org.neo4j.logging.Log;
+import org.neo4j.procedure.Description;
 import org.neo4j.procedure.TerminationGuard;
 
 public class PeriodicUtils {
 
     private PeriodicUtils() {}
 
     public static class JobInfo {
+        @Description("The name of the job.")
         public final String name;
+
+        @Description("The delay on the job.")
         public long delay;
+
+        @Description("The rate of the job.")
         public long rate;
+
+        @Description("If the job has completed.")
         public boolean done;
+
+        @Description("If the job has been cancelled.")
         public boolean cancelled;
 
         public JobInfo(String name) {

common/src/main/java/apoc/result/AssertSchemaResult.java

@@ -20,12 +20,22 @@
 
 import java.util.Arrays;
 import java.util.List;
+import org.neo4j.procedure.Description;
 
 public class AssertSchemaResult {
+    @Description("The label associated with the constraint or index.")
     public final Object label;
+
+    @Description("The property key associated with the constraint or index.")
     public final String key;
+
+    @Description("The property keys associated with the constraint or index.")
     public final List<String> keys;
+
+    @Description("Whether or not this is a uniqueness constraint.")
     public boolean unique = false;
+
+    @Description("The action applied to this constraint or index; can be [\"KEPT\", \"CREATED\", \"DROPPED\"]")
     public String action = "KEPT";
 
     public AssertSchemaResult(Object label, List<String> keys) {

common/src/main/java/apoc/result/ByteArrayResult.java

@@ -18,9 +18,12 @@
  */
 package apoc.result;
 
+import org.neo4j.procedure.Description;
+
 public class ByteArrayResult {
     public static final ByteArrayResult NULL = new ByteArrayResult(null);
 
+    @Description("The data as a bytearray.")
     public final byte[] value;
 
     public ByteArrayResult(byte[] value) {