Skip to content

Commit 80302b4

Browse files
ti-chi-botti-chi-bot
authored
add _tidb_rowid document (#21446) (#21474)
1 parent 0b78c62 commit 80302b4

File tree

5 files changed

+168
-5
lines changed

5 files changed

+168
-5
lines changed

‎TOC.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -621,6 +621,7 @@
621621
- 属性
622622
- [AUTO_INCREMENT](/auto-increment.md)
623623
- [AUTO_RANDOM](/auto-random.md)
624+
- [_tidb_rowid](/tidb-rowid.md)
624625
- [SHARD_ROW_ID_BITS](/shard-row-id-bits.md)
625626
- [字面值](/literal-values.md)
626627
- [Schema 对象名](/schema-object-names.md)

‎clustered-indexes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ summary: 本文档介绍了聚簇索引的概念、使用场景、使用方法
99

1010
目前 TiDB 中含有主键的表分为以下两类：
1111

12-
- `NONCLUSTERED`，表示该表的主键为非聚簇索引。在非聚簇索引表中，行数据的键由 TiDB 内部隐式分配的 `_tidb_rowid` 构成，而主键本质上是唯一索引，因此非聚簇索引表存储一行至少需要两个键值对，分别为
12+
- `NONCLUSTERED`，表示该表的主键为非聚簇索引。在非聚簇索引表中，行数据的键由 TiDB 内部隐式分配的 [`_tidb_rowid`](/tidb-rowid.md) 值构成，而主键本质上是唯一索引，因此非聚簇索引表存储一行至少需要两个键值对，分别为
1313
- `_tidb_rowid`（键）- 行数据（值）
1414
- 主键列数据（键） - `_tidb_rowid`（值）
1515
- `CLUSTERED`，表示该表的主键为聚簇索引。在聚簇索引表中，行数据的键由用户给定的主键列数据构成，因此聚簇索引表存储一行至少只要一个键值对，即

‎shard-row-id-bits.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,11 @@ summary: 介绍 TiDB 的 `SHARD_ROW_ID_BITS` 表属性。
55

66
# SHARD_ROW_ID_BITS
77

8-
本文介绍表属性 `SHARD_ROW_ID_BITS`，它用来设置隐式 `_tidb_rowid` 分片数量的 bit 位数。
8+
本文介绍表属性 `SHARD_ROW_ID_BITS`，它用来设置隐式 [`_tidb_rowid`](/tidb-rowid.md) 分片数量的 bit 位数。
99

1010
## 基本概念
1111

12-
对于非[聚簇索引](/clustered-indexes.md)主键或没有主键的表，TiDB 会使用一个隐式的自增 rowid。大量执行 `INSERT` 插入语句时会把数据集中写入单个 Region，造成写入热点。
12+
对于非聚簇索引主键或没有主键的表，TiDB 会使用内部自动生成的 [`_tidb_rowid`](/tidb-rowid.md) 作为隐式自增 rowid。大量执行 `INSERT` 插入语句时会把数据集中写入单个 Region，造成写入热点。
1313

1414
通过设置 `SHARD_ROW_ID_BITS`，可以把 rowid 打散写入多个不同的 Region，缓解写入热点问题。
1515

@@ -23,9 +23,13 @@ summary: 介绍 TiDB 的 `SHARD_ROW_ID_BITS` 表属性。
2323
|--------|--------|--------------|
2424
| 1 bit | `S` bits | `63-S` bits |
2525

26-
- 自增位的值保存在 TiKV 中，由 TiDB 按顺序分配，每次分配后值会自增 1。自增位确保了 `_tidb_rowid` 列的值全局唯一。当自增位的值耗尽后（即达到最大值时），再次自动分配时会报 `Failed to read auto-increment value from storage engine` 错误。
26+
- 自增位的值保存在 TiKV 中，由 TiDB 按顺序分配，每次分配后值会自增 1。当自增位的值耗尽后（即达到最大值时），再次自动分配时会报 `Failed to read auto-increment value from storage engine` 错误。
2727
- 关于 `_tidb_rowid` 取值范围：最终生成值包含的最大位数 = 分片位 + 自增位，最大值为 `(2^63)-1`。
2828

29+
> **警告：**
30+
>
31+
> `_tidb_rowid` 是 TiDB 内部隐式分配的行 ID。不要假定它在所有情况下都是全局唯一的。对于未使用聚簇索引的分区表，`ALTER TABLE ... EXCHANGE PARTITION` 操作可能会导致不同分区具有相同的 `_tidb_rowid` 值。详情请参阅 [`_tidb_rowid`](/tidb-rowid.md)。
32+
2933
> **注意：**
3034
>
3135
> 分片位长度 (`S`) 的选取：

‎sql-statements/sql-statement-show-table-next-rowid.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ summary: TiDB 数据库中 SHOW TABLE NEXT_ROW_ID 的使用概况。
77

88
`SHOW TABLE NEXT_ROW_ID` 语句用于显示用户表中某些特殊列的详情，主要包含以下几种类型：
99

10-
* TiDB 创建的 `AUTO_INCREMENT` 类型列，即 `_tidb_rowid` 列
10+
* TiDB 自动管理的隐藏行 ID 列 [`_tidb_rowid`](/tidb-rowid.md)
1111
* 用户创建的 `AUTO_INCREMENT` 类型列
1212
* 用户创建的 [`AUTO_RANDOM`](/auto-random.md) 类型列
1313
* 用户创建的 [`SEQUENCE`](/sql-statements/sql-statement-create-sequence.md) 对象信息
@@ -70,3 +70,4 @@ show table t next_row_id;
7070
* [CREATE TABLE](/sql-statements/sql-statement-create-table.md)
7171
* [AUTO_RANDOM](/auto-random.md)
7272
* [CREATE_SEQUENCE](/sql-statements/sql-statement-create-sequence.md)
73+
* [_tidb_rowid](/tidb-rowid.md)

‎tidb-rowid.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
title: _tidb_rowid
3+
summary: 了解 `_tidb_rowid` 是什么，何时可用，以及如何安全地使用它。
4+
---
5+
6+
# _tidb_rowid
7+
8+
`_tidb_rowid` 是 TiDB 自动生成的一个隐藏系统列，在没有使用聚簇索引的表中作为表的内部行 ID。你无法在表结构中定义或修改此列，但当表使用 `_tidb_rowid` 作为其内部行 ID 时，可以在 SQL 语句中引用它。
9+
10+
在当前实现中，`_tidb_rowid` 是一个由 TiDB 自动维护的 `BIGINT NOT NULL` 列。
11+
12+
> **警告：**
13+
>
14+
> - 不要假设 `_tidb_rowid` 在所有情况下都是全局唯一的。对于不使用聚簇索引的分区表，执行 `ALTER TABLE ... EXCHANGE PARTITION` 后，不同分区之间可能出现相同的 `_tidb_rowid`。
15+
> - 如果你需要一个稳定的唯一标识符，请定义并使用显式主键，而不是依赖 `_tidb_rowid`。
16+
17+
## `_tidb_rowid` 何时可用
18+
19+
当表没有使用聚簇主键作为行的唯一标识时，TiDB 会使用 `_tidb_rowid` 来标识每一行。实际上，这意味着以下表类型会使用 `_tidb_rowid`：
20+
21+
- 没有主键的表
22+
- 主键显式定义为 `NONCLUSTERED` 的表
23+
24+
`_tidb_rowid` 不适用于使用聚簇索引的表，即主键定义为 `CLUSTERED` 的表（无论是单列主键还是复合主键）。
25+
26+
以下示例显示了区别：
27+
28+
```sql
29+
CREATE TABLE t1 (a INT, b VARCHAR(20));
30+
CREATE TABLE t2 (id BIGINT PRIMARY KEY NONCLUSTERED, a INT);
31+
CREATE TABLE t3 (id BIGINT PRIMARY KEY CLUSTERED, a INT);
32+
```
33+
34+
对于 `t1` 和 `t2`，你可以查询 `_tidb_rowid`，因为这两个表没有使用聚簇索引作为行标识：
35+
36+
```sql
37+
SELECT _tidb_rowid, a, b FROM t1;
38+
SELECT _tidb_rowid, id, a FROM t2;
39+
```
40+
41+
对于 `t3`，`_tidb_rowid` 不可用，因为该表使用了聚簇索引作为行标识，：
42+
43+
```sql
44+
SELECT _tidb_rowid, id, a FROM t3;
45+
```
46+
47+
```sql
48+
ERROR 1054 (42S22): Unknown column '_tidb_rowid' in 'field list'
49+
```
50+
51+
## 读取 `_tidb_rowid`
52+
53+
对于使用了 `_tidb_rowid` 的表，你可以在 `SELECT` 语句中查询 `_tidb_rowid`。这对于分页查询、故障排除和批量处理等任务非常有用。
54+
55+
示例：
56+
57+
```sql
58+
CREATE TABLE t (a INT, b VARCHAR(20));
59+
INSERT INTO t VALUES (1, 'x'), (2, 'y');
60+
61+
SELECT _tidb_rowid, a, b FROM t ORDER BY _tidb_rowid;
62+
```
63+
64+
```sql
65+
+-------------+---+---+
66+
| _tidb_rowid | a | b |
67+
+-------------+---+---+
68+
| 1 | 1 | x |
69+
| 2 | 2 | y |
70+
+-------------+---+---+
71+
```
72+
73+
要查看 TiDB 将要分配的下一个行 ID 值，请使用 `SHOW TABLE ... NEXT_ROW_ID`：
74+
75+
```sql
76+
SHOW TABLE t NEXT_ROW_ID;
77+
```
78+
79+
```sql
80+
+-----------------------+------------+-------------+--------------------+-------------+
81+
| DB_NAME | TABLE_NAME | COLUMN_NAME | NEXT_GLOBAL_ROW_ID | ID_TYPE |
82+
+-----------------------+------------+-------------+--------------------+-------------+
83+
| update_doc_rowid_test | t | _tidb_rowid | 30001 | _TIDB_ROWID |
84+
+-----------------------+------------+-------------+--------------------+-------------+
85+
```
86+
87+
## 写入 `_tidb_rowid`
88+
89+
默认情况下，TiDB 不允许通过 `INSERT`、`REPLACE` 或 `UPDATE` 语句中直接写入 `_tidb_rowid`。
90+
91+
```sql
92+
INSERT INTO t(_tidb_rowid, a, b) VALUES (101, 4, 'w');
93+
```
94+
95+
```sql
96+
ERROR 1105 (HY000): insert, update and replace statements for _tidb_rowid are not supported
97+
```
98+
99+
在数据导入或迁移场景中，如需保留原始行 ID，请先启用系统变量 [`tidb_opt_write_row_id`](/system-variables.md#tidb_opt_write_row_id)：
100+
101+
```sql
102+
SET @@tidb_opt_write_row_id = ON;
103+
INSERT INTO t(_tidb_rowid, a, b) VALUES (100, 3, 'z');
104+
SET @@tidb_opt_write_row_id = OFF;
105+
106+
SELECT _tidb_rowid, a, b FROM t WHERE _tidb_rowid = 100;
107+
```
108+
109+
```sql
110+
+-------------+---+---+
111+
| _tidb_rowid | a | b |
112+
+-------------+---+---+
113+
| 100 | 3 | z |
114+
+-------------+---+---+
115+
```
116+
117+
> **警告：**
118+
>
119+
> `tidb_opt_write_row_id` 仅用于导入和迁移场景。不推荐用于常规应用程序写入。
120+
121+
## 限制
122+
123+
- 不能创建名为 `_tidb_rowid` 的用户列。
124+
- 不能将现有用户列重命名为 `_tidb_rowid`。
125+
- `_tidb_rowid` 是 TiDB 内部列，不适合作为业务主键或长期标识。
126+
- 在分区的非聚簇表上，`_tidb_rowid` 的值不保证在分区之间是唯一的。执行 `EXCHANGE PARTITION` 后，不同分区可能包含具有相同 `_tidb_rowid` 值的行。
127+
- `_tidb_rowid` 是否存在取决于表结构。对于使用聚簇索引的表，应使用主键作为行标识。
128+
129+
## 解决热点问题
130+
131+
对于使用 `_tidb_rowid` 的表，TiDB 默认按递增顺序分配行 ID。在写密集型工作负载下，这可能会导致写热点。
132+
133+
要缓解此问题（针对依赖 `_tidb_rowid` 作为行 ID 的表），请考虑使用 [`SHARD_ROW_ID_BITS`](/shard-row-id-bits.md)将行 ID 打散分布，并在需要时使用 [`PRE_SPLIT_REGIONS`](/sql-statements/sql-statement-split-region.md#pre_split_regions) 提前分裂 Region。
134+
135+
示例：
136+
137+
```sql
138+
CREATE TABLE t (
139+
id BIGINT PRIMARY KEY NONCLUSTERED,
140+
c INT
141+
) SHARD_ROW_ID_BITS = 4;
142+
```
143+
144+
`SHARD_ROW_ID_BITS` 仅适用于使用 `_tidb_rowid` 的表，不适用于聚簇索引表。
145+
146+
## 相关语句和变量
147+
148+
- [`SHOW TABLE NEXT_ROW_ID`](/sql-statements/sql-statement-show-table-next-rowid.md)：显示 TiDB 将要分配的下一个行 ID
149+
- [`SHARD_ROW_ID_BITS`](/shard-row-id-bits.md)：分片隐式行 ID 以减少热点
150+
- [`Clustered Indexes`](/clustered-indexes.md)：解释了何时表使用主键而不是 `_tidb_rowid`
151+
- [`tidb_opt_write_row_id`](/system-variables.md#tidb_opt_write_row_id)：控制是否允许写入 `_tidb_rowid`
152+
153+
## 另请参阅
154+
155+
- [`CREATE TABLE`](/sql-statements/sql-statement-create-table.md)
156+
- [`AUTO_INCREMENT`](/auto-increment.md)
157+
- [非事务 DML 语句](/non-transactional-dml.md)

0 commit comments

Comments
 (0)