Update follower read and learner read descriptions #21470
+7
−2
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -33,7 +33,7 @@ Default: leader | |||||||||
| This variable is used to set the expected data read mode. | ||||||||||
|
|
||||||||||
| - When the value of `tidb_replica_read` is set to `leader` or an empty string, TiDB maintains its default behavior and sends all read operations to the leader replica to perform. | ||||||||||
| - When the value of `tidb_replica_read` is set to `follower`, TiDB selects a follower replica of the Region to perform all read operations. When a Region has learner replicas, TiDB also considers reading data from learner replicas. In this case, follower replicas and learner replicas have the same priority. If there are no available follower or learner replicas in the current Region, TiDB will read from the leader replica. | ||||||||||
| - When the value of `tidb_replica_read` is set to `leader-and-follower`, TiDB can select any replicas to perform read operations. In this mode, read requests are load balanced between the leader and follower. | ||||||||||
| - When the value of `tidb_replica_read` is set to `prefer-leader`, TiDB prefers to select the leader replica to perform read operations. If the leader replica is obviously slow in processing read operations (such as caused by disk or network performance jitter), TiDB will select other available follower replicas to perform read operations. | ||||||||||
| - When the value of `tidb_replica_read` is set to `closest-replicas`, TiDB prefers to select a replica in the same availability zone to perform read operations, which can be a leader or a follower. If there is no replica in the same availability zone, TiDB reads from the leader replica. | ||||||||||
|
|
@@ -42,13 +42,18 @@ This variable is used to set the expected data read mode. | |||||||||
| - If the estimated result of a read request is greater than or equal to the value of [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630), TiDB prefers to select a replica in the same availability zone for read operations. To avoid unbalanced distribution of read traffic across availability zones, TiDB dynamically detects the distribution of availability zones for all online TiDB and TiKV nodes. In each availability zone, the number of TiDB nodes whose `closest-adaptive` configuration takes effect is limited, which is always the same as the number of TiDB nodes in the availability zone with the fewest TiDB nodes, and the other TiDB nodes automatically read from the leader replica. For example, if TiDB nodes are distributed across 3 availability zones (A, B, and C), where A and B each contains 3 TiDB nodes and C contains only 2 TiDB nodes, the number of TiDB nodes whose `closest-adaptive` configuration takes effect in each availability zone is 2, and the other TiDB node in each of the A and B availability zones automatically selects the leader replica for read operations. | ||||||||||
| - If the estimated result of a read request is less than the value of [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630), TiDB can only select the leader replica for read operations. | ||||||||||
|
|
||||||||||
| - When the value of `tidb_replica_read` is set to `learner`, TiDB reads data from the learner replica. If there is no available learner replica in the Region, TiDB will read data from available leader or follower replicas. | ||||||||||
|
There was a problem hiding this comment. To improve clarity and adhere to the style guide's preference for present tense, rephrase this sentence to be more direct and concise.12 Style Guide References
Suggested change
Footnotes |
||||||||||
|
|
||||||||||
| <CustomContent platform="tidb"> | ||||||||||
|
|
||||||||||
| > **Note:** | ||||||||||
| > | ||||||||||
| > When the value of `tidb_replica_read` is set to `closest-replicas` or `closest-adaptive`, you need to configure the cluster to ensure that replicas are distributed across availability zones according to the specified configuration. To configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV, refer to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/v1.4/configure-a-tidb-cluster#high-availability-of-data). | ||||||||||
| > | ||||||||||
| > For TiDB versions up to and including v7.5: | ||||||||||
| > | ||||||||||
| > - When the value of `tidb_replica_read` is set to `follower` and no follower or learner replicas are available, TiDB returns an error. | ||||||||||
| > - When the value of `tidb_replica_read` is set to `learner` and no learner replicas are available, TiDB returns an error. | ||||||||||
|
Comment on lines
+55
to
+56
There was a problem hiding this comment. To align with the style guide's recommendation of using the second person ("you"), rephrase these points. This makes the documentation more user-centric.1 Style Guide References
Suggested change
Footnotes |
||||||||||
|
|
||||||||||
| </CustomContent> | ||||||||||
|
|
||||||||||
|
|
||||||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For better readability and conciseness, combine the sentences describing the behavior for
followerreads. This makes the logic easier to follow.12Style Guide References
Footnotes
The style guide emphasizes clarity, simplicity, completeness, and readability. (link) ↩
The style guide recommends avoiding unnecessary words and repetition. (link) ↩