reference: add user documentation for auto_random feature #1875
Conversation
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
TomShawn
added
dev
translation/from-docs-cn
|
@tangenta PTAL, thanks! |
yikeke
reviewed
Mar 3, 2020
|
|
||
| - Determines whether to allow using `AUTO_RANDOM`. | ||
| - Default value: `false` | ||
| - By default, TiDB does not supporting using `AUTO_RANDOM`. When the value is `true`, you cannot set `alter-primary-key` to `true` at the same time. |
There was a problem hiding this comment.
Suggested change
| - By default, TiDB does not supporting using `AUTO_RANDOM`. When the value is `true`, you cannot set `alter-primary-key` to `true` at the same time. | |
| - By default, TiDB does not support using `AUTO_RANDOM`. When the value is `true`, you cannot set `alter-primary-key` to `true` at the same time. |
|
|
||
| > **Warning:** | ||
| > | ||
| > `AUTO_RANDOM` is still an experimental feature. It is recommended that you **DO NOT** use the attribute in the production environment. In later TiDB versions, the syntax or semantics of `AUTO_RANDOM` might change. |
There was a problem hiding this comment.
Suggested change
| > `AUTO_RANDOM` is still an experimental feature. It is recommended that you **DO NOT** use the attribute in the production environment. In later TiDB versions, the syntax or semantics of `AUTO_RANDOM` might change. | |
| > `AUTO_RANDOM` is still an experimental feature. It is **NOT** recommended that you use the attribute in the production environment. In later TiDB versions, the syntax or semantics of `AUTO_RANDOM` might change. |
|
|
||
| ## User scenario | ||
|
|
||
| When you write data intensively into TiDB which has the table with a primary key of the auto-increment integer type, hotspot problem might occur. To solve the hotspot problem in this scenario, you can use the `AUTO_RANDOM` attribute. Refer to [Highly Concurrent Write Best Practices](/reference/best-practices/high-concurrency.md#complex-hotspot-problems) for details. |
There was a problem hiding this comment.
Suggested change
| When you write data intensively into TiDB which has the table with a primary key of the auto-increment integer type, hotspot problem might occur. To solve the hotspot problem in this scenario, you can use the `AUTO_RANDOM` attribute. Refer to [Highly Concurrent Write Best Practices](/reference/best-practices/high-concurrency.md#complex-hotspot-problems) for details. | |
| When you write data intensively into TiDB and TiDB has the table with a primary key of the auto-increment integer type, a hotspot issue might occur. To solve this issue, you can use the `AUTO_RANDOM` attribute. Refer to [Highly Concurrent Write Best Practices](/reference/best-practices/high-concurrency.md#complex-hotspot-problems) for details. |
|
|
||
| When you write data intensively into TiDB which has the table with a primary key of the auto-increment integer type, hotspot problem might occur. To solve the hotspot problem in this scenario, you can use the `AUTO_RANDOM` attribute. Refer to [Highly Concurrent Write Best Practices](/reference/best-practices/high-concurrency.md#complex-hotspot-problems) for details. | ||
|
|
||
| Take the following `CREATE TABLE` statement as an example: |
There was a problem hiding this comment.
Suggested change
| Take the following `CREATE TABLE` statement as an example: | |
| Take the following created table as an example: |
| create table t (a int primary key auto_increment, b varchar(255)) | ||
| ``` | ||
|
|
||
| After creating a table by executing the above statement, execute a large number of `INSERT` statements on the newly-created table. These `INSERT` statements do not specify the values of the primary key. See the following example: |
There was a problem hiding this comment.
Suggested change
| After creating a table by executing the above statement, execute a large number of `INSERT` statements on the newly-created table. These `INSERT` statements do not specify the values of the primary key. See the following example: | |
| On this `t` table, you execute a large number of `INSERT` statements that do not specify the values of the primary key as below: |
| Then execute the `INSERT` statement such as `INSERT INTO t(b) values...`. | ||
|
|
||
| + If the `INSERT` statement does not specify the values of the integer primary key column (column `a`), TiDB automatically assigns values to this column. These values are not necessarily auto-increment or continuous but are unique, which avoids the hotspot problem caused by continuous row IDs. | ||
| + If the `INSERT` statement explicitly specifies the values of the integer primary key column, TiDB saves these values as they are, which works similarly to the `AUTO_INCREMENT` attribute. |
There was a problem hiding this comment.
Suggested change
| + If the `INSERT` statement explicitly specifies the values of the integer primary key column, TiDB saves these values as they are, which works similarly to the `AUTO_INCREMENT` attribute. | |
| + If the `INSERT` statement explicitly specifies the values of the integer primary key column, TiDB saves these values, which works similarly to the `AUTO_INCREMENT` attribute. |
|
|
||
| TiDB automatically assigns values in the following way: | ||
|
|
||
| The highest five digits of the row value in binary (namely, shard bits) is determined by the starting time of the current transaction. The remaining digits are assigned values in an auto-increment way. |
There was a problem hiding this comment.
Suggested change
| The highest five digits of the row value in binary (namely, shard bits) is determined by the starting time of the current transaction. The remaining digits are assigned values in an auto-increment way. | |
| The highest five digits of the row value in binary (namely, shard bits) are determined by the starting time of the current transaction. The remaining digits are assigned values in an auto-increment order. |
|
|
||
| In the above `CREATE TABLE` statement, `3` shard bits are specified. The range of the number of shard bits is `[1, field_max_bits)`. `field_max_bits` is the length of bits occupied by the primary key column. | ||
|
|
||
| In the `TIDB_ROW_ID_SHARDING_INFO` row of the `information_schema.tables` system table, the value of the table with the `AUTO_RANDOM` attribute is `PK_AUTO_RANDOM_BITS=x`. In this value, `x` is the number of shard bits. |
There was a problem hiding this comment.
Suggested change
| In the `TIDB_ROW_ID_SHARDING_INFO` row of the `information_schema.tables` system table, the value of the table with the `AUTO_RANDOM` attribute is `PK_AUTO_RANDOM_BITS=x`. In this value, `x` is the number of shard bits. | |
| For tables with the `AUTO_RANDOM` attribute, the value of the `TIDB_ROW_ID_SHARDING_INFO` column in the `information_schema.tables` system table is `PK_AUTO_RANDOM_BITS=x`. `x` is the number of shard bits. |
Please confirm with the author whether the following understanding of the original Chinese is right:
对于含有 AUTO_RANDOM 属性的表，在系统表 information_schema.tables 的 TIDB_ROW_ID_SHARDING_INFO 列的值为。。。
There was a problem hiding this comment.
Yes, this is correct.
|
|
||
| The above two statements have the same meaning. | ||
|
|
||
| In the result of `show create table`, the `AUTO_RANDOM` attribute is commented out. This comment includes a version number (for example, `/*T!30100 auto_random */`). `30100` in the example indicates that the `AUTO_RANDOM` attribute is introduced in v3.1.0. TiDB of lower versions ignore the `AUTO_RANDOM` attribute in the above comment. |
There was a problem hiding this comment.
Suggested change
| In the result of `show create table`, the `AUTO_RANDOM` attribute is commented out. This comment includes a version number (for example, `/*T!30100 auto_random */`). `30100` in the example indicates that the `AUTO_RANDOM` attribute is introduced in v3.1.0. TiDB of lower versions ignore the `AUTO_RANDOM` attribute in the above comment. | |
| In the result of `show create table`, the `AUTO_RANDOM` attribute is commented out. This comment includes a version number (for example, `/*T!30100 auto_random */`). Here `30100` indicates that the `AUTO_RANDOM` attribute is introduced in v3.1.0. TiDB of a lower version ignores the `AUTO_RANDOM` attribute in the above comment. |
|
|
||
| In the result of `show create table`, the `AUTO_RANDOM` attribute is commented out. This comment includes a version number (for example, `/*T!30100 auto_random */`). `30100` in the example indicates that the `AUTO_RANDOM` attribute is introduced in v3.1.0. TiDB of lower versions ignore the `AUTO_RANDOM` attribute in the above comment. | ||
|
|
||
| This attribute supports forward compatibility, namely, downgrade compatibility. TiDB earlier than v3.1.0 ignores the `AUTO_RANDOM` attribute of a table (with the above comment), so the table can be used by TiDB of earlier versions. |
There was a problem hiding this comment.
Suggested change
| This attribute supports forward compatibility, namely, downgrade compatibility. TiDB earlier than v3.1.0 ignores the `AUTO_RANDOM` attribute of a table (with the above comment), so the table can be used by TiDB of earlier versions. | |
| This attribute supports forward compatibility, namely, downgrade compatibility. TiDB earlier than v3.1.0 ignores the `AUTO_RANDOM` attribute of a table (with the above comment), so TiDB of earlier versions can also use the table with the attribute. |
yikeke
reviewed
Mar 3, 2020
| - You cannot change the column type of the primary key column that is specified with `AUTO_RANDOM` attribute. | ||
| - You cannot specify `AUTO_RANDOM` and `AUTO_INCREMENT` for the same column at the same time. | ||
| - You cannot specify `AUTO_RANDOM` and `DEFAULT` (the default value of a column) for the same column at the same time. | ||
| - It is recommended that you do not explicitly specify a value for the row with the `AUTO_RANDOM` attribute when you insert data. Otherwise, the numeral values to be automatically assigned might be used up in advance. |
There was a problem hiding this comment.
Suggested change
| - It is recommended that you do not explicitly specify a value for the row with the `AUTO_RANDOM` attribute when you insert data. Otherwise, the numeral values to be automatically assigned might be used up in advance. | |
| - It is **not** recommended that you explicitly specify a value for the column with the `AUTO_RANDOM` attribute when you insert data. Otherwise, the numeral values that can be automatically assigned for this table might be used up in advance. |
|
@yikeke Comments addressed, PTAL again, thanks! |
TomShawn
added
the
status/can-merge
|
/run-all-tests |
sre-bot
pushed a commit
to sre-bot/docs
that referenced
this pull request
Mar 3, 2020
Signed-off-by: sre-bot <sre-bot@pingcap.com>
1 task
|
cherry pick to release-3.1 in PR #1932 |
yikeke
pushed a commit
that referenced
this pull request
Mar 3, 2020
1 task
sticnarf
pushed a commit
to sticnarf/docs
that referenced
this pull request
Mar 20, 2020
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
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.
What is changed, added or deleted?
Add a user document for the
auto_randomfeature.What is the related PR or file link(s)?
Important Notice:
If your changes apply to multiple TiDB documentation versions, to trigger the bot to cherry-pick this PR to other release branches, make sure you add labels such as: