Documentation changes related to the storage engine (#360)

* Remove unnecessary mentions of RocksDB

* collection.any() presumably uses an optimization for retrieving a single document

* Intermediate commits only apply to standalone AQL queries

They are disabled for JavaScript Transactions and Stream Transactions, including AQL queries that run inside of such transactions. They are also disabled for batch operations in the Document API.

* Cast startup option default values to string

This prevents Hugo from rendering some numbers in scientific notation (e.g. 1.34217728e+08)

* Apply to 3.10 and 3.11

Author: Simran-B

site/content/3.10/aql/data-queries.md

@@ -541,12 +541,12 @@ On a single server, data modification operations are executed transactionally.
 If a data modification operation fails, any changes made by it are rolled 
 back automatically as if they never happened. 
 
-If the RocksDB engine is used and intermediate commits are enabled, a query may 
-execute intermediate transaction commits in case the running transaction (AQL
-query) hits the specified size thresholds. In this case, the query's operations 
-carried out so far are committed and not rolled back in case of a later abort/rollback. 
-That behavior can be controlled by adjusting the intermediate commit settings for 
-the RocksDB engine. 
+A query may execute intermediate transaction commits in case the running
+transaction (AQL query) hits the specified size thresholds. In this case, the
+query's operations carried out so far are committed and not rolled back in case
+of a later abort/rollback. This behavior can be controlled by adjusting the
+intermediate commit settings for the RocksDB engine. See
+[Known limitations for AQL queries](fundamentals/limitations.md#storage-engine-properties).
 
 In a cluster, AQL data modification queries are not executed transactionally.
 Additionally, AQL queries with `UPDATE`, `REPLACE`, `UPSERT`, or `REMOVE`

site/content/3.10/aql/fundamentals/limitations.md

@@ -7,6 +7,8 @@ description: >-
   they operate on, as well as design limitations to be aware of
 archetype: default
 ---
+## Complexity limitations
+
 The following hard-coded limitations exist for AQL queries:
 
 - An AQL query cannot use more than _1000_ result registers.
@@ -37,7 +39,9 @@ of different collections. Please also consider that large queries (in terms of
 intermediate result size or final result size) can use considerable amounts of
 memory and may hit the configurable memory limits for AQL queries.
 
-The following other limitations are known for AQL queries:
+## Design limitations
+
+The following design limitations are known for AQL queries:
 
 - Subqueries that are used inside expressions are pulled out of these
   expressions and executed beforehand. That means that subqueries do not
@@ -52,3 +56,50 @@ The following other limitations are known for AQL queries:
   [`WITH` statement](../high-level-operations/with.md). To make the `WITH` statement
   required in single server as well (e.g. for testing a migration to cluster),
   please start the server with the option `--query.require-with`.
+
+## Storage engine properties
+
+{{< info >}}
+The following restrictions and limitations do not apply to JavaScript Transactions
+and Stream Transactions, including AQL queries that run inside such transactions.
+Their intended use case is for smaller transactions with full transactional
+guarantees. So the following only applies to standalone AQL queries.
+{{< /info >}}
+
+Data of ongoing transactions is stored in RAM. Transactions that get too big
+(in terms of number of operations involved or the total size of data created or
+modified by the transaction) are committed automatically. Effectively, this
+means that big user transactions are split into multiple smaller RocksDB
+transactions that are committed individually. The entire user transaction does
+not necessarily have ACID properties in this case.
+
+The following startup options can be used to control the RAM usage and automatic
+intermediate commits for the RocksDB engine:
+
+- `--rocksdb.max-transaction-size`
+
+  Transaction size limit (in bytes). Transactions store all keys and values in
+  RAM, so large transactions run the risk of causing out-of-memory situations.
+  This setting allows you to ensure that does not happen by limiting the size of
+  any individual transaction. Transactions whose operations would consume more
+  RAM than this threshold value will abort automatically with error 32 ("resource
+  limit exceeded").
+
+- `--rocksdb.intermediate-commit-size`
+
+  If the size of all operations in a transaction reaches this threshold, the transaction
+  is committed automatically and a new transaction is started. The value is specified in bytes.
+
+- `--rocksdb.intermediate-commit-count`
+
+  If the number of operations in a transaction reaches this value, the transaction is
+  committed automatically and a new transaction is started.
+
+The above values can also be adjusted per query, for example, by setting the
+following attributes in the call to `db._query()` in the JavaScript API:
+
+- `maxTransactionSize`: transaction size limit in bytes
+- `intermediateCommitSize`: maximum total size of operations after which an intermediate
+  commit is performed automatically
+- `intermediateCommitCount`: maximum number of operations after which an intermediate
+  commit is performed automatically

site/content/3.10/aql/high-level-operations/for.md

@@ -93,7 +93,7 @@ Also see [Combining queries with subqueries](../fundamentals/subqueries.md).
 ## Options
 
 For collections and Views, the `FOR` construct supports an optional `OPTIONS`
-clause to modify behavior. The general syntax is:
+clause to modify the behavior. The general syntax is as follows:
 
 <pre><code>FOR <em>variableName</em> IN <em>expression</em> OPTIONS { <em>option</em>: <em>value</em>, <em>...</em> }</code></pre>
 

site/content/3.10/aql/high-level-operations/insert.md

@@ -205,12 +205,12 @@ FOR i IN 1..100
 On a single server, an insert operation is executed transactionally in an
 all-or-nothing fashion.
 
-If the RocksDB engine is used and intermediate commits are enabled, a query may
-execute intermediate transaction commits in case the running transaction (AQL
-query) hits the specified size thresholds. In this case, the query's operations
-carried out so far will be committed and not rolled back in case of a later
-abort/rollback. That behavior can be controlled by adjusting the intermediate
-commit settings for the RocksDB engine.
+A query may execute intermediate transaction commits in case the running
+transaction (AQL query) hits the specified size thresholds. In this case, the
+query's operations carried out so far are committed and not rolled back in case
+of a later abort/rollback. This behavior can be controlled by adjusting the
+intermediate commit settings for the RocksDB engine. See
+[Known limitations for AQL queries](../fundamentals/limitations.md#storage-engine-properties).
 
 For sharded collections, the entire query and/or insert operation may not be
 transactional, especially if it involves different shards and/or DB-Servers.

site/content/3.10/aql/high-level-operations/remove.md

@@ -175,12 +175,12 @@ FOR u IN users
 On a single server, the document removal is executed transactionally in an
 all-or-nothing fashion.
 
-If the RocksDB engine is used and intermediate commits are enabled, a query may
-execute intermediate transaction commits in case the running transaction (AQL
-query) hits the specified size thresholds. In this case, the query's operations
-carried out so far will be committed and not rolled back in case of a later
-abort/rollback. That behavior can be controlled by adjusting the intermediate
-commit settings for the RocksDB engine. 
+A query may execute intermediate transaction commits in case the running
+transaction (AQL query) hits the specified size thresholds. In this case, the
+query's operations carried out so far are committed and not rolled back in case
+of a later abort/rollback. This behavior can be controlled by adjusting the
+intermediate commit settings for the RocksDB engine. See
+[Known limitations for AQL queries](../fundamentals/limitations.md#storage-engine-properties).
 
 For sharded collections, the entire query and/or remove operation may not be
 transactional, especially if it involves different shards and/or DB-Servers.

site/content/3.10/aql/high-level-operations/replace.md

@@ -296,12 +296,12 @@ FOR u IN users
 On a single server, replace operations are executed transactionally in an
 all-or-nothing fashion.
 
-If the RocksDB engine is used and intermediate commits are enabled, a query may
-execute intermediate transaction commits in case the running transaction (AQL
-query) hits the specified size thresholds. In this case, the query's operations
-carried out so far are committed and not rolled back in case of a later
-abort/rollback. That behavior can be controlled by adjusting the intermediate
-commit settings for the RocksDB engine. 
+A query may execute intermediate transaction commits in case the running
+transaction (AQL query) hits the specified size thresholds. In this case, the
+query's operations carried out so far are committed and not rolled back in case
+of a later abort/rollback. This behavior can be controlled by adjusting the
+intermediate commit settings for the RocksDB engine. See
+[Known limitations for AQL queries](../fundamentals/limitations.md#storage-engine-properties).
 
 For sharded collections, the entire query and/or replace operation may not be
 transactional, especially if it involves different shards and/or DB-Servers.

site/content/3.10/aql/high-level-operations/update.md

@@ -419,12 +419,12 @@ FOR u IN users
 On a single server, updates are executed transactionally in an all-or-nothing
 fashion.
 
-If the RocksDB engine is used and intermediate commits are enabled, a query may
-execute intermediate transaction commits in case the running transaction (AQL
-query) hits the specified size thresholds. In this case, the query's operations
-carried out so far are committed and not rolled back in case of a later
-abort/rollback. That behavior can be controlled by adjusting the intermediate
-commit settings for the RocksDB engine.
+A query may execute intermediate transaction commits in case the running
+transaction (AQL query) hits the specified size thresholds. In this case, the
+query's operations carried out so far are committed and not rolled back in case
+of a later abort/rollback. This behavior can be controlled by adjusting the
+intermediate commit settings for the RocksDB engine. See
+[Known limitations for AQL queries](../fundamentals/limitations.md#storage-engine-properties).
 
 For sharded collections, the entire query and/or update operation may not be
 transactional, especially if it involves different shards and/or DB-Servers.

site/content/3.10/aql/high-level-operations/with.md

@@ -40,9 +40,9 @@ at the very start of the query.
 
 ## Usage
 
-With RocksDB as storage engine, the `WITH` operation is only required if you
-use a cluster deployment and only for AQL queries that dynamically read from
-vertex collections as part of graph traversals.
+The `WITH` operation is only required if you use a cluster deployment and only
+for AQL queries that dynamically read from vertex collections as part of
+graph traversals.
 
 You can enable the `--query.require-with` startup option to make single server
 instances require `WITH` declarations like cluster deployments to ease development,

site/content/3.10/deploy/architecture/storage-engine.md

@@ -39,30 +39,21 @@ the same time, a write conflict is raised. It is possible to exclusively lock
 collections when executing AQL. This avoids write conflicts, but also inhibits
 concurrent writes.
 
-ArangoDB uses RocksDB's transactions to implement the ArangoDB transaction
-handling. Therefore, the same restrictions apply for ArangoDB transactions when
-using the RocksDB engine.
-
-RocksDB imposes a limit on the transaction size. It is optimized to
-handle small transactions very efficiently, but is effectively limiting
-the total size of transactions. If you have an operation that modifies a lot of
-documents, it is necessary to commit data in-between. This is done automatically
-for AQL by default. Transactions that get too big (in terms of number of
-operations involved or the total size of data modified by the transaction)
+ArangoDB uses RocksDB transactions to implement the transaction handling for
+standalone AQL queries (outside of JavaScript Transactions and Stream Transactions).
+
+RocksDB imposes a limit on the transaction size. It is optimized to handle small
+transactions very efficiently, but is effectively limiting the total size of
+transactions. If you have an AQL query that modifies a lot of documents, it is
+necessary to commit data in-between. Transactions that get too big (in terms of
+number of operations involved or the total size of data modified by the transaction)
 are committed automatically. Effectively, this means that big user transactions
 are split into multiple smaller RocksDB transactions that are committed individually.
 The entire user transaction does not necessarily have ACID properties in this case.
 
-The threshold values for transaction sizes can be configured globally using the
-startup options
-
-- [`--rocksdb.intermediate-commit-size`](../../components/arangodb-server/options.md#--rocksdbintermediate-commit-size)
-
-- [`--rocksdb.intermediate-commit-count`](../../components/arangodb-server/options.md#--rocksdbintermediate-commit-count)
-
-- [`--rocksdb.max-transaction-size`](../../components/arangodb-server/options.md#--rocksdbmax-transaction-size)
-
-It is also possible to override these thresholds per transaction.
+The threshold values for transaction sizes can be configured globally as well as
+overridden per transaction. See
+[Known limitations for AQL queries](../../aql/fundamentals/limitations.md#storage-engine-properties).
 
 ### Write-ahead log
 

site/content/3.10/deploy/oneshard.md

@@ -276,10 +276,13 @@ on the leader shards in a cluster, a few things need to be considered:
 - The collection option `writeConcern: 2` makes sure that a transaction is only
   successful if at least one follower shard is in sync with the leader shard,
   for a total of two shard replicas.
-- The RocksDB engine supports intermediate commits for larger document
-  operations, potentially breaking the atomicity of transactions. To prevent
+- The RocksDB storage engine uses intermediate commits for larger document
+  operations carried out by standalone AQL queries
+  (outside of JavaScript Transactions and Stream Transactions).
+  This potentially breaks the atomicity of transactions. To prevent
   this for individual queries you can increase `intermediateCommitSize`
   (default 512 MB) and `intermediateCommitCount` accordingly as query option.
+  Also see [Known limitations for AQL queries](../aql/fundamentals/limitations.md#storage-engine-properties).
 
 ### Limitations