From 2e58c77203a856570c162b01634eebd4cf9b12f6 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Thu, 28 May 2020 20:23:00 +0800 Subject: [PATCH] add Coprocessor cache doc (#2616) * Update command line flags for pd configruation (#2596) Signed-off-by: nolouch * Remove upgrade-tiflash.md (#2597) * Remove upgrade-tiflash.md Duplicated with TiDB's upgrade manual. * delete a link Co-authored-by: yikeke * add Coprocessor cache doc * Update coprocessor-cache.md * Update tidb-configuration-file.md * Apply suggestions from code review Co-authored-by: Wenxuan * Update tidb-configuration-file.md Co-authored-by: Keke Yi <40977455+yikeke@users.noreply.github.com> Co-authored-by: ShuNing Co-authored-by: Flowyi Co-authored-by: yikeke Co-authored-by: Wenxuan Co-authored-by: Keke Yi <40977455+yikeke@users.noreply.github.com> --- TOC.md | 1 + coprocessor-cache.md | 39 ++++++++++++++++++++++++++++++++++++++ tidb-configuration-file.md | 28 +++++++++++++++++++++++++++ 3 files changed, 68 insertions(+) create mode 100644 coprocessor-cache.md diff --git a/TOC.md b/TOC.md index a21bd0e2f24cf..89453bf36810d 100644 --- a/TOC.md +++ b/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) diff --git a/coprocessor-cache.md b/coprocessor-cache.md new file mode 100644 index 0000000000000..a6bfb10d15cac --- /dev/null +++ b/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. diff --git a/tidb-configuration-file.md b/tidb-configuration-file.md index fe8fe00668003..6cc5497d173c5 100644 --- a/tidb-configuration-file.md +++ b/tidb-configuration-file.md @@ -6,6 +6,7 @@ aliases: ['/docs/stable/reference/configuration/tidb-server/configuration-file/' --- + # 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 New in v4.0.0 + +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.