From 4da8f8d9bb395374cb453182522355c77596bc29 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Thu, 29 Jul 2021 15:08:15 +0800 Subject: [PATCH 1/4] update stale read doc for ga --- as-of-timestamp.md | 8 ++------ experimental-features.md | 1 - stale-read.md | 4 ---- 3 files changed, 2 insertions(+), 11 deletions(-) diff --git a/as-of-timestamp.md b/as-of-timestamp.md index baa31b39a4a45..ce63be0ff055e 100644 --- a/as-of-timestamp.md +++ b/as-of-timestamp.md @@ -9,12 +9,10 @@ This document describes how to perform the [Stale Read](/stale-read.md) feature > **Warning:** > -> Currently, Stale Read is an experimental feature. It is not recommended to use it in the production environment. -> > Currently, you cannot use Stale Read together with TiFlash. If your SQL query contains the `AS OF TIMESTAMP` clause and TiDB might read data from TiFlash replicas, you might encounter an error with a message like `ERROR 1105 (HY000): stale requests require tikv backend`. > > To fix the problem, disable TiFlash replicas for your Stale Read query. To do that, perform one of the following operations: -> +> > - Use the `set session tidb_isolation_read_engines='tidb,tikv'` variable. > - Use the [hint](/optimizer-hints.md#read_from_storagetiflasht1_name--tl_name--tikvt2_name--tl_name-) to enforce TiDB to read data from TiKV. @@ -47,9 +45,7 @@ Here are some examples of the `AS OF TIMESTAMP` clause: > > In addition to specifying a timestamp, the most common use of the `AS OF TIMESTAMP` clause is to read data that is several seconds old. If this approach is used, it is recommended to read historical data older than 5 seconds. > -> You need to deploy the NTP service for your TiDB and PD nodes when you use Stale Read. This avoids the situation where the specified timestamp used by TiDB goes ahead of the latest TSO allocating progress (such as a timestamp several seconds ahead), or is later than the GC safe point timestamp. When the specified timestamp goes beyond the service scope, TiDB returns an error or waits for the transaction to commit. -> -> The `Prepare` statement and the `AS OF TIMESTAMP` syntax are not perfectly compatible. It is not recommended to use them together. +> You need to deploy the NTP service for your TiDB and PD nodes when you use Stale Read. This avoids the situation where the specified timestamp used by TiDB goes ahead of the latest TSO allocating progress (such as a timestamp several seconds ahead), or is later than the GC safe point timestamp. When the specified timestamp goes beyond the service scope, TiDB returns an error. ## Usage examples diff --git a/experimental-features.md b/experimental-features.md index 8fa56efb15532..8ce5db812f33e 100644 --- a/experimental-features.md +++ b/experimental-features.md @@ -29,7 +29,6 @@ This document introduces the experimental features of TiDB in different versions + [User-Defined Variables](/user-defined-variables.md). + [JSON data type](/data-type-json.md) and [JSON functions](/functions-and-operators/json-functions.md). + [View](/information-schema/information-schema-views.md). -+ [Stale Read](/stale-read.md). ## Configuration management diff --git a/stale-read.md b/stale-read.md index 3736c20ca58e2..ddccc76b31d05 100644 --- a/stale-read.md +++ b/stale-read.md @@ -9,10 +9,6 @@ This document describes the usage scenarios of Stale Read. Stale Read is a mecha When you are using Steal Read, TiDB will randomly select a replica for data reading, which means that all replicas are available for data reading. If your application cannot tolerate reading non-real-time data, do not use Stale Read; otherwise, the data read from the replica might not be the latest data written into TiDB. -> **Warning:** -> -> Currently, Stale Read is an experimental feature. It is not recommended to use it in the production environment. - ## Scenario examples + Scenario one: If a transaction only involves read operations and is tolerant of data staleness to some extent, you can use Stale Read to get historical data. Using Stale Read, TiDB makes the query requests sent to any replica at the expense of some real-time performance, and thus increases the throughput of query executions. Especially in some scenarios where small tables are queried, if strongly consistent reads are used, leader might be concentrated on a certain storage node, causing the query pressure to be concentrated on that node as well. Therefore, that node might become a bottleneck for the whole query. Stale Read, however, can improve the overall query throughput and significantly improve the query performance. From 502b43ff0d7cb1eb860fc9d86ec3d7443a9b002e Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Thu, 29 Jul 2021 15:38:29 +0800 Subject: [PATCH 2/4] Update stale-read.md --- stale-read.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/stale-read.md b/stale-read.md index ddccc76b31d05..93741ad8cce3d 100644 --- a/stale-read.md +++ b/stale-read.md @@ -9,6 +9,9 @@ This document describes the usage scenarios of Stale Read. Stale Read is a mecha When you are using Steal Read, TiDB will randomly select a replica for data reading, which means that all replicas are available for data reading. If your application cannot tolerate reading non-real-time data, do not use Stale Read; otherwise, the data read from the replica might not be the latest data written into TiDB. +> **Note:** +> Since v5.1.1, Stale Read is a feature for general availability (GA). + ## Scenario examples + Scenario one: If a transaction only involves read operations and is tolerant of data staleness to some extent, you can use Stale Read to get historical data. Using Stale Read, TiDB makes the query requests sent to any replica at the expense of some real-time performance, and thus increases the throughput of query executions. Especially in some scenarios where small tables are queried, if strongly consistent reads are used, leader might be concentrated on a certain storage node, causing the query pressure to be concentrated on that node as well. Therefore, that node might become a bottleneck for the whole query. Stale Read, however, can improve the overall query throughput and significantly improve the query performance. From e2c82987da83ac13b976dd1f48ee54c7cb82aed3 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Thu, 29 Jul 2021 15:38:56 +0800 Subject: [PATCH 3/4] Update stale-read.md --- stale-read.md | 1 + 1 file changed, 1 insertion(+) diff --git a/stale-read.md b/stale-read.md index 93741ad8cce3d..40a6e71639d1c 100644 --- a/stale-read.md +++ b/stale-read.md @@ -10,6 +10,7 @@ This document describes the usage scenarios of Stale Read. Stale Read is a mecha When you are using Steal Read, TiDB will randomly select a replica for data reading, which means that all replicas are available for data reading. If your application cannot tolerate reading non-real-time data, do not use Stale Read; otherwise, the data read from the replica might not be the latest data written into TiDB. > **Note:** +> > Since v5.1.1, Stale Read is a feature for general availability (GA). ## Scenario examples From 1dd2489277a4054aa2e804cf7015b1b1207cff4a Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Thu, 29 Jul 2021 15:39:10 +0800 Subject: [PATCH 4/4] Update as-of-timestamp.md --- as-of-timestamp.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/as-of-timestamp.md b/as-of-timestamp.md index ce63be0ff055e..01399f06adc4f 100644 --- a/as-of-timestamp.md +++ b/as-of-timestamp.md @@ -46,6 +46,8 @@ Here are some examples of the `AS OF TIMESTAMP` clause: > In addition to specifying a timestamp, the most common use of the `AS OF TIMESTAMP` clause is to read data that is several seconds old. If this approach is used, it is recommended to read historical data older than 5 seconds. > > You need to deploy the NTP service for your TiDB and PD nodes when you use Stale Read. This avoids the situation where the specified timestamp used by TiDB goes ahead of the latest TSO allocating progress (such as a timestamp several seconds ahead), or is later than the GC safe point timestamp. When the specified timestamp goes beyond the service scope, TiDB returns an error. +> +> Before v5.1.1, the `Prepare` statement and the `AS OF TIMESTAMP` syntax are not perfectly compatible. It is not recommended to use them together. Since v5.1.1, the `Prepare` statement and the `AS OF TIMESTAMP` syntax are fully compatible, and you can use them together. ## Usage examples