Fixes #3843: Deprecate mapParallel procedure and update docs (#4229)

docs/asciidoc/modules/ROOT/examples/generated-documentation/apoc.cypher.mapParallel.adoc

@@ -2,4 +2,5 @@
 
 `apoc.cypher.mapParallel(fragment, params, list-to-parallelize) yield value` - executes fragment in parallel batches with the list segments being assigned to _
 ¦label:procedure[]
+¦label:deprecated[]
 ¦label:apoc-extended[]

docs/asciidoc/modules/ROOT/examples/generated-documentation/apoc.cypher.mapParallel2.adoc

@@ -2,4 +2,5 @@
 
 `apoc.cypher.mapParallel2(fragment, params, list-to-parallelize) yield value` - executes fragment in parallel batches with the list segments being assigned to _
 ¦label:procedure[]
+¦label:deprecated[]
 ¦label:apoc-extended[]

docs/asciidoc/modules/ROOT/pages/overview/apoc.cypher/apoc.cypher.mapParallel.adoc

@@ -5,7 +5,8 @@ This file is generated by DocsTest, so don't change it!
 = apoc.cypher.mapParallel
 :description: This section contains reference documentation for the apoc.cypher.mapParallel procedure.
 
-label:procedure[] label:apoc-extended[]
+
+label:procedure[] label:apoc-extended[] label:deprecated[]
 
 [.emphasis]
 apoc.cypher.mapParallel(fragment, params, list-to-parallelize) yield value - executes fragment in parallel batches with the list segments being assigned to _
@@ -33,5 +34,47 @@ apoc.cypher.mapParallel(fragment :: STRING?, params :: MAP?, list :: LIST? OF AN
 |value|MAP?
 |===
 
+Note: this procedure is deprecated.
+Use Cypher runtime parallel for single read-only operations:
+
+[source]
+----
+CYPHER runtime=parallel
+CALL {
+  MATCH (p:Post)
+  WITH
+    CASE
+      WHEN p.updatedAt IS NULL THEN [p.createdAt]
+      ELSE [p.createdAt, p.updatedAt]
+    END AS activityDates
+  UNWIND activityDates AS activityDate
+  RETURN activityDate
+  UNION ALL
+  MATCH (u:User)
+  UNWIND [u.createdAt, u.accessedAt] AS activityDate
+  RETURN activityDate
+}
+RETURN activityDate.year AS year,
+       activityDate.month AS month,
+       count(*) AS activity
+ORDER BY activity DESC, year, month
+LIMIT 10
+----
+
+or, alternatively, for write operations use IN CONCURRENT TRANSACTIONS:
+
+[source]
+----
+:auto
+CALL {
+  UNWIND range(0,9) as b
+  MATCH (m:Movie { ranking: b }) RETURN m
+} IN CONCURRENT TRANSACTIONS
+WITH m.ranking as rank
+MATCH (n:Movie)
+SET n.ranking = 11
+RETURN n
+----
+
 xref::cypher-execution/parallel.adoc[More documentation of apoc.cypher.mapParallel,role=more information]
 

docs/asciidoc/modules/ROOT/pages/overview/apoc.cypher/apoc.cypher.mapParallel2.adoc

@@ -5,7 +5,7 @@ This file is generated by DocsTest, so don't change it!
 = apoc.cypher.mapParallel2
 :description: This section contains reference documentation for the apoc.cypher.mapParallel2 procedure.
 
-label:procedure[] label:apoc-extended[]
+label:procedure[] label:apoc-extended[] label:deprecated[]
 
 [.emphasis]
 apoc.cypher.mapParallel2(fragment, params, list-to-parallelize) yield value - executes fragment in parallel batches with the list segments being assigned to _
@@ -35,5 +35,47 @@ apoc.cypher.mapParallel2(fragment :: STRING?, params :: MAP?, list :: LIST? OF A
 |value|MAP?
 |===
 
+Note: this procedure is deprecated.
+Use Cypher runtime parallel for single read-only operations:
+
+[source]
+----
+CYPHER runtime=parallel
+CALL {
+  MATCH (p:Post)
+  WITH
+    CASE
+      WHEN p.updatedAt IS NULL THEN [p.createdAt]
+      ELSE [p.createdAt, p.updatedAt]
+    END AS activityDates
+  UNWIND activityDates AS activityDate
+  RETURN activityDate
+  UNION ALL
+  MATCH (u:User)
+  UNWIND [u.createdAt, u.accessedAt] AS activityDate
+  RETURN activityDate
+}
+RETURN activityDate.year AS year,
+       activityDate.month AS month,
+       count(*) AS activity
+ORDER BY activity DESC, year, month
+LIMIT 10
+----
+
+or, alternatively, for write operations use IN CONCURRENT TRANSACTIONS:
+
+[source]
+----
+:auto
+CALL {
+  UNWIND range(0,9) as b
+  MATCH (m:Movie { ranking: b }) RETURN m
+} IN CONCURRENT TRANSACTIONS
+WITH m.ranking as rank
+MATCH (n:Movie)
+SET n.ranking = 11
+RETURN n
+----
+
 xref::cypher-execution/parallel.adoc[More documentation of apoc.cypher.mapParallel2,role=more information]
 

docs/asciidoc/modules/ROOT/pages/overview/apoc.cypher/index.adoc

@@ -11,11 +11,11 @@ This file is generated by DocsTest, so don't change it!
 |xref::overview/apoc.cypher/apoc.cypher.mapParallel.adoc[apoc.cypher.mapParallel icon:book[]]
 
 apoc.cypher.mapParallel(fragment, params, list-to-parallelize) yield value - executes fragment in parallel batches with the list segments being assigned to _
-|label:procedure[]
+|label:procedure[] label:deprecated[]
 |xref::overview/apoc.cypher/apoc.cypher.mapParallel2.adoc[apoc.cypher.mapParallel2 icon:book[]]
 
 apoc.cypher.mapParallel2(fragment, params, list-to-parallelize) yield value - executes fragment in parallel batches with the list segments being assigned to _
-|label:procedure[]
+|label:procedure[] label:deprecated[]
 |xref::overview/apoc.cypher/apoc.cypher.parallel.adoc[apoc.cypher.parallel icon:book[]]
 
 apoc.cypher.parallel(fragment, `paramMap`, `keyList`) yield value - executes fragments in parallel through a list defined in `paramMap` with a key `keyList`

extended/src/main/java/apoc/cypher/CypherExtended.java

@@ -399,7 +399,8 @@ public Stream<CypherStatementMapResult> parallel(@Name("fragment") String fragme
         */
     }
 
-    @Procedure
+    @Deprecated
+    @Procedure(deprecatedBy = "Cypher subqueries like: `CYPHER runtime=parallel CALL {...} ... ` or `CALL {...} IN CONCURRENT TRANSACTIONS ... `")
     @Description("apoc.cypher.mapParallel(fragment, params, list-to-parallelize) yield value - executes fragment in parallel batches with the list segments being assigned to _")
     public Stream<MapResult> mapParallel(@Name("fragment") String fragment, @Name("params") Map<String, Object> params, @Name("list") List<Object> data) {
         final String statement = withParamsAndIterator(fragment, params.keySet(), "_");
@@ -409,7 +410,8 @@ public Stream<MapResult> mapParallel(@Name("fragment") String fragment, @Name("p
                 .map(MapResult::new);
     }
 
-    @Procedure
+    @Deprecated
+    @Procedure(deprecatedBy = "Cypher subqueries like: `CYPHER runtime=parallel CALL {...} ... ` or `CALL {...} IN CONCURRENT TRANSACTIONS ... `")
     @Description("apoc.cypher.mapParallel2(fragment, params, list-to-parallelize) yield value - executes fragment in parallel batches with the list segments being assigned to _")
     public Stream<MapResult> mapParallel2(@Name("fragment") String fragment, @Name("params") Map<String, Object> params, @Name("list") List<Object> data, @Name("partitions") long partitions,@Name(value = "timeout",defaultValue = "10") long timeout) {
         final String statement = withParamsAndIterator(fragment, params.keySet(), "_");