DOC-145: Added documentation for APM-84 (#1060)

* Added documentation for APM-84 * Fixed query option name * Removed explanation from release * review * Update invocation-with-arangosh.md * wording, formatting * formatting, wording, added links to release notes * Update release-notes-new-features310.md * Update release-notes-new-features310.md * Update invocation-with-arangosh.md Co-authored-by: ansoboleva <93702078+ansoboleva@users.noreply.github.com>

Author: cpjulia

3.10/aql/invocation-with-arangosh.md

@@ -242,6 +242,44 @@ In the ArangoDB Enterprise Edition there is an additional parameter:
  into sync. The default value is 60.0 (seconds). When the max time has been reached
  the query will be stopped.
 
+Additional parameters for spilling data from the query onto disk
+-----------------------------------------------------------------
+
+Starting from ArangoDB 3.10, there are two additional parameters that allow spilling 
+intermediate data from a query onto a disk to descrease the memory usage.
+ 
+{% hint 'info' %}
+The option of spilling data from RAM onto disk is experimental and is turned off 
+by default. This parameter currently only has effect for sorting - 
+for a query that uses the SORT keyword, but without LIMIT.
+Also, the query results are still built up entirely in RAM on coordinators
+and single servers for non-streaming queries. To avoid the buildup of
+the entire query result in RAM, a streaming query should be used.
+{% endhint %}
+
+- `spillOverThresholdNumRows`: This parameter allows for input data and 
+ intermediate results to be spilled onto disk for a query execution
+ after the number of rows reaches the specified value. This is 
+ used for decreasing the memory usage during the query execution. In a query 
+ that iterates over a collection that contains documents, each row is a 
+ document and, in a query that iterates over temporary values 
+ (i.e. `FOR i IN 1..100`), each row is one of such temporary values. 
+ This parameter is experimental and is only taken into account if a path for a
+ directory to store the temporary data is provided with the [`--temp.intermediate-results-path`
+ server startup option](../programs-arangod-query.html#aql-query-with-spilling-input-data-to-disk). 
+ Default value: 5000000 rows.
+
+
+- `spillOverThresholdMemoryUsage`: This parameter allows for input data and 
+ intermediate results to be spilled onto disk for a query execution 
+ after the memory usage reaches the specified value (in bytes). This 
+ is used for decreasing the memory usage during the query execution. This 
+ parameter is experimental and is only taken into account if a path for a 
+ directory to store the temporary data is provided with the [`--temp.intermediate-results-path`
+ server startup option](../programs-arangod-query.html#aql-query-with-spilling-input-data-to-disk). 
+ Default value: 128MB.
+
+
 With _createStatement (ArangoStatement)
 ---------------------------------------
 

3.10/programs-arangod-query.md

@@ -314,3 +314,63 @@ query results cache, as queries on system collections are internal to ArangoDB a
 only use space in the query results cache unnecessarily.
 
 The default value is *false*.
+
+
+## AQL Query with spilling input data to disk 
+
+<small>Introduced in: v3.10.0 </small>
+
+With the parameters mentioned below, queries can execute with storing input 
+and intermediate results temporarily on disk to decrease the memory usage 
+a specified threshold is reached. 
+
+{% hint 'info' %}
+This feature is experimental and is turned off by default.
+Also, the query results are still built up entirely in RAM on coordinators
+and single servers for non-streaming queries. To avoid the buildup of
+the entire query result in RAM, a streaming query should be used.
+{% endhint %}
+
+The threshold value to start spilling data onto disk is either 
+a number of rows in the query input or an amount of memory used in bytes, 
+which are both set as query options.
+
+The main parameter that must be provided for this feature to be active is 
+`--temp.intermediate-results-path`. This parameter specifies a path to a directory
+used to store temporary data. If such path is not provided, the feature of spilling data 
+onto the disk will not be activated.
+
+Hence, the following parameters do not have any effect, unless the parameter 
+mentioned above is provided with a directory path.
+The directory specified here must not be located underneath the instance's 
+database directory.
+
+
+- `--temp.-intermediate-results-encryption-hardware-acceleration`
+
+ Use Intel intrinsics-based encryption, requiring a CPU with the AES-NI 
+ instruction set. If turned off, then OpenSSL is used, which may use hardware-
+ accelarated encryption too. 
+ Default: `true`.
+
+- `--temp.intermediate-results-capacity`
+
+ Maximum capacity, in bytes, to use for ephemeral, intermediate results, meaning 
+ the maximum size allowed for the mentioned temporary storage. 
+ Default: 0 (unlimited).
+
+- `--temp.intermediate-results-encryption` 
+
+ Encrypt ephemeral, intermediate results on disk.
+ Default: `false`.
+
+
+- `--temp.intermediate-results-spillover-threshold-num-rows`
+
+ A number of result rows from which on a spillover from RAM to disk will happen.
+ Default: 5000000.
+
+- `--temp.intermediate-results-spillover-threshold-memory-usage`
+
+ Memory usage, in bytes, after which a spillover from RAM to disk will happen.
+ Default: 128MB.

3.10/release-notes-new-features310.md

@@ -517,6 +517,38 @@ arangoexport \
  ...
 ```
 
+
+Query changes for decreasing memory usage
+-----------------------------------------
+
+Queries can be executed with storing input and intermediate results temporarily
+on disk to descrease memory usage when a specified threshold is reached.
+
+{% hint 'info' %}
+This feature is experimental and is turned off by default.
+{% endhint %}
+
+The new parameters are listed below:
+
+- `--temp.intermediate-results-path`
+- `--temp.-intermediate-results-encryption-hardware-acceleration`
+- `--temp.intermediate-results-encryption`
+- `--temp.intermediate-results-spillover-threshold-num-rows`
+- `--temp.intermediate-results-spillover-threshold-memory-usage`
+
+Example:
+
+```
+arangod --temp.intermediate-results-path "tempDir" 
+--database.directory "myDir"
+--temp.-intermediate-results-encryption-hardware-acceleration true
+--temp.intermediate-results-encryption true 
+--temp.intermediate-results-spillover-threshold-num-rows 50000
+--temp.intermediate-results-spillover-threshold-memory-usage 134217728
+```
+
+For more information, refer to the [Query invocation](aql/invocation-with-arangosh.html#additional-parameters-for-spilling-data-from-the-query-onto-disk) and [Query options](programs-arangod-query.html#aql-query-with-spilling-input-data-to-disk) topics.
+
 Internal changes
 ----------------