New Cypher runtimes chapter (#688)

To be released alongside Parallel runtime.


Includes changes from the following PRs:
- #667
- #676
- #712
- #732

Author: JPryce-Aklundh

modules/ROOT/content-nav.adoc

@@ -84,19 +84,17 @@
 ** xref:constraints/syntax.adoc[]
 ** xref:constraints/examples.adoc[]
 
-* xref:query-tuning/index.adoc[]
-** xref:query-tuning/query-options.adoc[]
-** xref:query-tuning/query-profile.adoc[]
-** xref:query-tuning/indexes.adoc[]
-** xref:query-tuning/basic-example.adoc[]
-** xref:query-tuning/advanced-example.adoc[]
-** xref:query-tuning/using.adoc[]
-
-* xref:execution-plans/index.adoc[]
-** xref:execution-plans/db-hits.adoc[]
-** xref:execution-plans/operator-summary.adoc[]
-** xref:execution-plans/operators.adoc[]
-** xref:execution-plans/shortestpath-planning.adoc[]
+* xref:planning-and-tuning/index.adoc[]
+** xref:planning-and-tuning/execution-plans.adoc[]
+** xref:planning-and-tuning/operators/index.adoc[]
+*** xref:planning-and-tuning/operators/operators-detail.adoc[]
+** xref:planning-and-tuning/runtimes/index.adoc[]
+*** xref:planning-and-tuning/runtimes/concepts.adoc[Concepts]
+*** xref:planning-and-tuning/runtimes/reference.adoc[]
+** xref:planning-and-tuning/query-tuning/index.adoc[]
+*** xref:planning-and-tuning/query-tuning/indexes.adoc[]
+*** xref:planning-and-tuning/query-tuning/using.adoc[]
+*** xref:planning-and-tuning/query-tuning/query-options.adoc[]
 
 * xref:query-caches/index.adoc[]
 ** xref:query-caches/unified-query-caches.adoc[]
@@ -116,3 +114,4 @@
 
 * Appendix
 ** xref:styleguide.adoc[]
+** xref:appendix/tutorials/index.adoc[]

modules/ROOT/images/runtimes_cypher_lifecycle.svg

@@ -1,13 +1,11 @@
 :description: Example of some more subtle optimizations based on native index capabilities.
-
-
 [[advanced-query-tuning-example]]
 = Advanced query tuning example
 
 This page describes advanced query optimizations based on native index capabilities.
 
 One of the most important and useful ways of optimizing Cypher queries involves creating appropriate indexes.
-This is described in more detail in xref::indexes-for-search-performance.adoc[], and demonstrated in xref::query-tuning/basic-example.adoc[].
+This is described in more detail in xref::indexes-for-search-performance.adoc[], and demonstrated in xref::appendix/tutorials/basic-query-tuning.adoc[].
 In summary, an index will be based on the combination of a `Label` and a `property`.
 Any Cypher query that searches for nodes with a specific label and some predicate on the property (equality, range or existence) will be planned to use
 the index if the cost planner deems that to be the most efficient solution.

modules/ROOT/images/runtimes_execution_graph1.svg

@@ -607,7 +607,7 @@ RETURN p
 This query will find the *'Tom Hanks'* node but as the number of nodes in the database increase it will become slower and slower.
 We can profile the query to find out why that is.
 
-You can learn more about the options for profiling queries in xref::query-tuning/query-options.adoc[] but in this case you are going to prefix our query with `PROFILE`:
+You can learn more about the options for profiling queries in xref::planning-and-tuning/query-tuning/query-options.adoc[] but in this case you are going to prefix our query with `PROFILE`:
 
 [source, cypher]
 ----
@@ -646,9 +646,9 @@ ready to start consuming query after 17 ms, results consumed after another 10 ms
 The first thing to keep in mind when reading execution plans is that you need to read from the bottom up.
 
 In that vein, starting from the last row, the first thing you notice is that the value in the `Rows` column seems high given there is only one node with the name property *'Tom Hanks'* in the database.
-If you look across to the `Operator` column, you will see that xref::execution-plans/operators.adoc#query-plan-all-nodes-scan[AllNodesScan] has been used which means that the query planner scanned through all the nodes in the database.
+If you look across to the `Operator` column, you will see that xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-all-nodes-scan[AllNodesScan] has been used which means that the query planner scanned through all the nodes in the database.
 
-The xref::execution-plans/operators.adoc#query-plan-filter[Filter] operator which will check the `name` property on each of the nodes passed through by `AllNodesScan`.
+The xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-filter[Filter] operator which will check the `name` property on each of the nodes passed through by `AllNodesScan`.
 
 This seems like an inefficient way of finding *'Tom Hanks'* given that you are looking at many nodes that are not even people and therefore are not what you are looking for.
 
@@ -700,7 +700,7 @@ Total database accesses: 379, total allocated memory: 184
 ----
 
 This time the `Rows` value on the last row has reduced so you are not scanning some nodes that you were before which is a good start.
-The xref::execution-plans/operators.adoc#query-plan-node-by-label-scan[NodeByLabelScan] operator indicates that you achieved this by first doing a linear scan of all the `Person` nodes in the database.
+The xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-by-label-scan[NodeByLabelScan] operator indicates that you achieved this by first doing a linear scan of all the `Person` nodes in the database.
 
 Once you have done that, you can again scan through all those nodes using the `Filter` operator, comparing the name property of each one.
 
@@ -764,5 +764,5 @@ Total database accesses: 5, total allocated memory: 184
 1 row
 ----
 
-Our execution plan is down to a single row and uses the xref::execution-plans/operators.adoc#query-plan-node-index-seek[Node Index Seek] operator which does an index seek (see xref::indexes-for-search-performance.adoc[]) to find the appropriate node.
+Our execution plan is down to a single row and uses the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-index-seek[Node Index Seek] operator which does an index seek (see xref::indexes-for-search-performance.adoc[]) to find the appropriate node.
 

modules/ROOT/images/runtimes_execution_graph2.svg

@@ -0,0 +1,6 @@
+:description: List of available tutorials in the Cypher Manual.
+= Tutorials and extended examples
+
+* xref:appendix/tutorials/basic-query-tuning.adoc[]
+* xref:appendix/tutorials/advanced-query-tuning.adoc[]
+* xref:appendix/tutorials/shortestpath-planning.adoc[] - information about how to plan queries using the xref:patterns/concepts.adoc#shortest-path[`shortestPath()` function].

…pages/query-tuning/advanced-example.adoc …dix/tutorials/advanced-query-tuning.adocmodules/ROOT/pages/query-tuning/advanced-example.adoc renamed to modules/ROOT/pages/appendix/tutorials/advanced-query-tuning.adoc modules/ROOT/pages/query-tuning/advanced-example.adoc renamed to modules/ROOT/pages/appendix/tutorials/advanced-query-tuning.adoc

@@ -26,7 +26,7 @@ Therefore, in these cases, it is recommended to set `cypher.forbid_exhaustive_sh
 == Shortest path -- fast algorithm
 
 
-.Query evaluated with the fast algorithm
+.Query evaluated with the fast algorith
 ======
 
 ////

…OT/pages/query-tuning/basic-example.adoc …pendix/tutorials/basic-query-tuning.adocmodules/ROOT/pages/query-tuning/basic-example.adoc renamed to modules/ROOT/pages/appendix/tutorials/basic-query-tuning.adoc modules/ROOT/pages/query-tuning/basic-example.adoc renamed to modules/ROOT/pages/appendix/tutorials/basic-query-tuning.adoc

@@ -951,8 +951,8 @@ materialize the table of intermediate results before executing the next clause.
 This approach would consume a lot of memory for materializing the tables of intermediate results and would generally not perform well.
 
 Instead, Cypher will in general try to interleave the execution of clauses.
-This is called xref::execution-plans/index.adoc#eagerness-laziness[lazy evaluation].
+This is called xref::planning-and-tuning/execution-plans.adoc#laze-eager-evaluation[lazy evaluation].
 It only materializes intermediate results when needed.
 In many read-write queries it is unproblematic to execute clauses interleaved, but when it is not,
 Cypher must ensure that the table of intermediate results gets materialized at the right time(s).
-This is done by inserting an xref::execution-plans/operators.adoc#query-plan-eager[`Eager`] operator into the execution plan.
+This is done by inserting an xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-eager[`Eager`] operator into the execution plan.

modules/ROOT/pages/appendix/tutorials/index.adoc

@@ -234,22 +234,22 @@ m| xref:clauses/transaction-clauses.adoc#query-terminate-transactions[TERMINATE
 == Reading hints
 
 These comprise clauses used to specify planner hints when tuning a query.
-More details regarding the usage of these -- and query tuning in general -- can be found in xref::query-tuning/using.adoc[Planner hints and the USING keyword].
+More details regarding the usage of these -- and query tuning in general -- can be found in xref::planning-and-tuning/query-tuning/using.adoc[Planner hints and the USING keyword].
 
 [options="header"]
 |===
 | Hint | Description
 
-m| xref::query-tuning/using.adoc#query-using-index-hint[USING INDEX]
+m| xref::planning-and-tuning/query-tuning/using.adoc#query-using-index-hint[USING INDEX]
 | Index hints are used to specify which index, if any, the planner should use as a starting point.
 
-m| xref::query-tuning/using.adoc#query-using-index-hint[USING INDEX SEEK]
+m| xref::planning-and-tuning/query-tuning/using.adoc#query-using-index-hint[USING INDEX SEEK]
 | Index seek hint instructs the planner to use an index seek for this clause.
 
-m| xref::query-tuning/using.adoc#query-using-scan-hint[USING SCAN]
+m| xref::planning-and-tuning/query-tuning/using.adoc#query-using-scan-hint[USING SCAN]
 | Scan hints are used to force the planner to do a label scan (followed by a filtering operation) instead of using an index.
 
-m| xref::query-tuning/using.adoc#query-using-join-hint[USING JOIN]
+m| xref::planning-and-tuning/query-tuning/using.adoc#query-using-join-hint[USING JOIN]
 | Join hints are used to enforce a join operation at specified points.
 
 |===