From 9d81f381d23c1c141a3b7b4b42e971c60a8b5b0f Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Thu, 24 Jun 2021 18:03:49 +0800 Subject: [PATCH 1/3] Add note about stale read --- as-of-timestamp.md | 12 +++++++++++- experimental-features.md | 1 + stale-read.md | 4 ++++ 3 files changed, 16 insertions(+), 1 deletion(-) diff --git a/as-of-timestamp.md b/as-of-timestamp.md index 58d851d0cbd89..48d9ad9647640 100644 --- a/as-of-timestamp.md +++ b/as-of-timestamp.md @@ -7,6 +7,10 @@ summary: Learn how to read historical data using the `AS OF TIMESTAMP` statement This document describes how to perform the [Stale Read](/stale-read.md) feature using the `AS OF TIMESTAMP` clause to read historical data in TiDB, including specific usage examples and strategies for saving historical data. +> **Warning:** +> +> Currently, Stale Read is an experimental feature. It is not recommended to use it in the production environment. + TiDB supports reading historical data through a standard SQL interface, which is the `AS OF TIMESTAMP` SQL clause, without the need for special clients or drivers. After data is updated or deleted, you can read the historical data before the update or deletion using this SQL interface. > **Note:** @@ -32,7 +36,13 @@ Here are some examples of the `AS OF TIMESTAMP` clause: - `AS OF TIMESTAMP TIDB_BOUNDED_STALENESS('2016-10-08 16:45:26', '2016-10-08 16:45:29')`: Tells TiDB to read the data as new as possible within the time range of 16:45:26 to 16:45:29 on October 8, 2016. - `AS OF TIMESTAMP TIDB_BOUNDED_STALENESS(NOW() - INTERVAL 20 SECOND, NOW())`: Tells TiDB to read the data as new as possible within the time range of 20 seconds ago to the present. -Note that 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. +> **Note:** +> +> 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 of TiDB goes ahead of the latest TSO distribution progress (such as a timestamp several seconds ahead), or goes ahead of the timestamp of GC safe point. 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. ## Usage examples diff --git a/experimental-features.md b/experimental-features.md index 9f77f5cf18f9f..003a749b5867f 100644 --- a/experimental-features.md +++ b/experimental-features.md @@ -30,6 +30,7 @@ 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 00ee16e10e35c..0496cb1ed44cf 100644 --- a/stale-read.md +++ b/stale-read.md @@ -9,6 +9,10 @@ This document describes the usage scenarios of Stale Read. Stale Read is a mecha In terms of the internal implementation, Stale Read allows TiDB to read from any replica the data of the specified point in time or the data as new as possible within the specified time range, and to always ensure the data consistency constraint during the reading process. +> **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 sends the query requests to any replica of the corresponding data at the expense of some real-time performance, and thus increases the throughput of query executions. From 265a50b88c1a723a2d4bb21893b25f3111b3711a Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Thu, 24 Jun 2021 18:42:18 +0800 Subject: [PATCH 2/3] Update as-of-timestamp.md Co-authored-by: NingLin-P --- as-of-timestamp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/as-of-timestamp.md b/as-of-timestamp.md index 48d9ad9647640..c93f5c25e5fa7 100644 --- a/as-of-timestamp.md +++ b/as-of-timestamp.md @@ -40,7 +40,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 of TiDB goes ahead of the latest TSO distribution progress (such as a timestamp several seconds ahead), or goes ahead of the timestamp of GC safe point. When the specified timestamp goes beyond the service scope, TiDB returns an error or waits for the transaction to commit. +> 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 goes behind 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. From 02352624d3f9eb09f6006762a922cb743b1d4c6a Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Thu, 24 Jun 2021 19:08:10 +0800 Subject: [PATCH 3/3] Update as-of-timestamp.md Co-authored-by: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> --- as-of-timestamp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/as-of-timestamp.md b/as-of-timestamp.md index c93f5c25e5fa7..07fa1a9b2544b 100644 --- a/as-of-timestamp.md +++ b/as-of-timestamp.md @@ -40,7 +40,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 goes behind 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. +> 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.