add Coprocessor cache doc (#2616)

TOC.md

@@ -315,6 +315,7 @@
     - [Execution Plan Binding](/execution-plan-binding.md)
     - [Access Tables Using `IndexMerge`](/index-merge.md)
     - [Statement Summary Table](/statement-summary-tables.md)
+    - [Coprocessor Cache](/coprocessor-cache.md)
     - [Tune TiKV](/tune-tikv-performance.md)
   + Key Monitoring Metrics
     - [Overview](/grafana-overview-dashboard.md)

coprocessor-cache.md

@@ -0,0 +1,39 @@
+---
+title: Coprocessor Cache
+summary: Learn the features of Coprocessor Cache.
+category: reference
+---
+
+# Coprocessor Cache
+
+Starting from v4.0, the TiDB instance supports caching the results of the calculation that is pushed down to TiKV (the Coprocessor Cache feature), which can accelerate the calculation process in some scenarios.
+
+## Configuration
+
+You can configure Coprocessor Cache via the `tikv-client.copr-cache` configuration items in the TiDB configuration file. For details about how to enable and configure Coprocessor Cache, see [TiDB Configuration File](/tidb-configuration-file.md#tikv-clientcopr-cache-new-in-v400).
+
+## Feature description
+
++ When a SQL statement is executed on a single TiDB instance for the first time, the execution result is not cached.
++ Calculation results are cached in the memory of TiDB. If the TiDB instance is restarted, the cache becomes invalid.
++ The cache is not shared among TiDB instances.
++ Only push-down calculation result is cached. Even if cache is hit, TiDB still need to perform subsequent calculation.
++ The cache is in the unit of Region. Writing data to a Region causes the Region cache to be invalid. For this reason, the Coprocessor Cache feature mainly takes effect on the data that rarely changes.
++ When push-down calculation requests are the same, the cache is hit. Usually in the following scenarios, the push-down calculation requests are the same or partially the same:
+    - The SQL statements are the same. For example, the same SQL statement is executed repeatedly.
+
+        In this scenario, all the push-down calculation requests are consistent, and all requests can use the push-down calculation cache.
+
+    - The SQL statements contain a changing condition, and the other parts are consistent. The changing condition is the primary key of the table or the partition.
+
+        In this scenario, some of the push-down calculation requests are the same with some previous requests, and these calculation requests can use the cached (previous) push-down calculation result.
+
+    - The SQL statements contain multiple changing conditions and the other parts are consistent. The changing conditions exactly match a compound index column.
+
+        In this scenario, some of the push-down calculation requests are the same with some previous requests, and these calculation requests can use the cached (previous) push-down calculation result.
+
++ This feature is transparent to users. Enabling or disabling this feature does not affect the calculation result and only affects the SQL execution time.
+
+## Check the cache effect
+
+Currently (TiDB v4.0.0-rc.2), Coprocessor cache is still an experimental feature. Users cannot learn how many push-down requests hit the cache in a SQL statement, or understand the overall cache hits. The corresponding monitoring and checking method will be introduced in later TiDB versions.

tidb-configuration-file.md

@@ -6,6 +6,7 @@ aliases: ['/docs/stable/reference/configuration/tidb-server/configuration-file/'
 ---
 
 <!-- markdownlint-disable MD001 -->
+<!-- markdownlint-disable MD024 -->
 
 # TiDB Configuration File
 
@@ -417,6 +418,33 @@ The Plan Cache configuration of the `PREPARE` statement.
 - The threshold of the TiKV load. If the TiKV load exceeds this threshold, more `batch` packets are collected to relieve the pressure of TiKV. It is valid only when the value of `tikv-client.max-batch-size` is greater than `0`. It is recommended not to modify this value.
 - Default value: `200`
 
+## tikv-client.copr-cache <span class="version-mark">New in v4.0.0</span>
+
+This section introduces configuration items related to the Coprocessor Cache feature.
+
+### `enable`
+
+- Determines whether to enable [Coprocessor Cache](/coprocessor-cache.md).
+- Default value: `false` (which means that Coprocessor Cache is disabled by default)
+
+### `capacity-mb`
+
+- The total size of the cached data. When the cache space is full, old cache entries are evicted.
+- Default value: `1000`
+- Unit: MB
+
+### `admission-max-result-mb`
+
+- Specifies the largest single push-down calculation result set that can be cached. If the result set of a single push-down calculation returned on the Coprocessor is larger than the result set specified by this parameter, the result set is cached. Increasing this value means that more types of push-down requests are cached, but also cause the cache space to be occupied more easily. Note that the size of each push-down calculation result set is generally smaller than the size of the Region. Therefore, it is meaningless to set this value far beyond the size of a Region.
+- Default value: `10`
+- Unit: MB
+
+### `admission-min-process-ms`
+
+- Specifies the minimum calculation time for a single push-down calculation result set that can be cached. If the calculation time of a single push-down calculation on the Coprocessor is less than the time specified by this parameter, the result set is not cached. Requests that are processed quickly do not need to be cached, and only the requests that take a long time to process need to be cached, which makes the cache less likely to be evicted.
+- Default value: `5`
+- Unit: ms
+
 ### txn-local-latches
 
 Configuration related to the transaction latch. It is recommended to enable it when many local transaction conflicts occur.