diff --git a/as-of-timestamp.md b/as-of-timestamp.md index 58d851d0cbd89..07fa1a9b2544b 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 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. ## 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.