Add fillBlockCache option to bypass RocksDB block cache #14234 (#703)

Author: jsteemann

3.8/aql/invocation-with-arangosh.md

@@ -168,8 +168,17 @@ There are further options that can be passed in the *options* attribute of the *
   the query result cache is disabled, and that they will be automatically inserted into
   the query result cache when it is active in non-demand mode.
 
+- *fillBlockCache*: if set to *true* or not specified, this will make the query store
+  the data it reads via the RocksDB storage engine in the RocksDB block cache. This is
+  usually the desired behavior. The option can be set to *false* for queries that are
+  known to either read a lot of data that would thrash the block cache, or for queries
+  that read data known to be outside of the hot set. By setting the option
+  to *false*, data read by the query will not make it into the RocksDB block cache if
+  it is not already in there, thus leaving more room for the actual hot set.
+
 - *profile*: if set to *true* or *1*, returns extra timing information for the query. The timing
-  information is accessible via the *getExtra* method of the query result. Set to *2* the query will include execution stats per query plan node in sub-attribute *stats.nodes* of the *extra* return attribute.
+  information is accessible via the *getExtra* method of the query result. Set to *2* the query will
+  include execution stats per query plan node in sub-attribute *stats.nodes* of the *extra* return attribute.
   Additionally the query plan is returned in the sub-attribute *extra.plan*.
 
 - *maxWarningCount*: limits the number of warnings that are returned by the query if

3.8/release-notes-api-changes38.md

@@ -297,9 +297,16 @@ as a database only. It may have an effect for Foxx applications that use HTTP
   only be picked up for indexes of type "persistent", "hash" and "skiplist" (where the
   latter two are aliases for "persistent" nowadays).
 
-The REST endpoint at GET `/_api/collection/<collection>/checksum` now also works
-in cluster setups. In previous versions, this endpoint was not supported in cluster
-setups and returned HTTP 501 (Not implemented).
+- The REST endpoint at GET `/_api/collection/<collection>/checksum` now also works
+  in cluster setups. In previous versions, this endpoint was not supported in cluster
+  setups and returned HTTP 501 (Not implemented).
+
+- The HTTP REST API endpoint `POST /_api/cursor` can now handle an 
+  additional sub-attribute `fillBlockCache` for its `options` attribute.
+  `fillBlockCache` controls whether the to-be-executed query should
+  populate the RocksDB block cache with the data read by the query.
+  This is an optional attribute, and its default value is `true`, meaning
+  that the block cache will be populated (introduced in v3.8.1).
 
 ### Endpoints deprecated
 

3.9/aql/invocation-with-arangosh.md

@@ -168,8 +168,17 @@ There are further options that can be passed in the *options* attribute of the *
   the query result cache is disabled, and that they will be automatically inserted into
   the query result cache when it is active in non-demand mode.
 
+- *fillBlockCache*: if set to *true* or not specified, this will make the query store
+  the data it reads via the RocksDB storage engine in the RocksDB block cache. This is
+  usually the desired behavior. The option can be set to *false* for queries that are
+  known to either read a lot of data that would thrash the block cache, or for queries
+  that read data known to be outside of the hot set. By setting the option
+  to *false*, data read by the query will not make it into the RocksDB block cache if
+  it is not already in there, thus leaving more room for the actual hot set.
+
 - *profile*: if set to *true* or *1*, returns extra timing information for the query. The timing
-  information is accessible via the *getExtra* method of the query result. Set to *2* the query will include execution stats per query plan node in sub-attribute *stats.nodes* of the *extra* return attribute.
+  information is accessible via the *getExtra* method of the query result. Set to *2* the query will
+  include execution stats per query plan node in sub-attribute *stats.nodes* of the *extra* return attribute.
   Additionally the query plan is returned in the sub-attribute *extra.plan*.
 
 - *maxWarningCount*: limits the number of warnings that are returned by the query if

3.9/release-notes-api-changes39.md

@@ -19,6 +19,14 @@ integrations for ArangoDB 3.9.
 
 ### Endpoints augmented
 
+The HTTP REST API endpoint `POST /_api/cursor` can now handle an 
+additional sub-attribute `fillBlockCache` for its `options` attribute.
+`fillBlockCache` controls whether the to-be-executed query should
+populate the RocksDB block cache with the data read by the query.
+This is an optional attribute, and its default value is `true`, meaning
+that the block cache will be populated. This functionality was also backported
+to v3.8.1.
+
 ### Endpoints moved
 
 ### Endpoints removed