update the description related to clustered indexes (pingcap#5834)

oryx2 · Mar 26, 2021 · 9c7ddf0 · 9c7ddf0
1 parent 32c1a0b
commit 9c7ddf0
Show file tree

Hide file tree

Showing 4 changed files with 17 additions and 17 deletions.
diff --git a/br/backup-and-restore-tool.md b/br/backup-and-restore-tool.md
@@ -76,7 +76,7 @@ BR 和 TiDB 集群的兼容性问题分为以下两方面：
 
 | 功能 | 相关 issue | 解决方式 |
 |  ----  | ----  | ----- |
-| 聚簇索引 | [#565](https://github.com/pingcap/br/issues/565)       | 确保备份时 tidb_enable_clustered_index 变量和恢复时一致，否则会导致数据不一致的问题，例如 `default not found` 和数据索引不一致。 |
+| 聚簇索引 | [#565](https://github.com/pingcap/br/issues/565)       | 确保备份时 tidb_enable_clustered_index 全局变量和恢复时一致，否则会导致数据不一致的问题，例如 `default not found` 和数据索引不一致。 |
 | New collation  | [#352](https://github.com/pingcap/br/issues/352)       | 确保恢复时集群的 new_collations_enabled_on_first_bootstrap 和备份时的一致，否则会导致数据索引不一致和 checksum 通不过。 |
 | 恢复集群开启 TiCDC 同步 | [#364](https://github.com/pingcap/br/issues/364#issuecomment-646813965) |  TiKV 暂不能将 BR ingest 的 SST 文件下推到 TiCDC，因此使用 BR 恢复时候需要关闭 TiCDC。 |
 

diff --git a/clustered-indexes.md b/clustered-indexes.md
@@ -50,7 +50,7 @@ CREATE TABLE t (a BIGINT, b VARCHAR(255), PRIMARY KEY(a, b) NONCLUSTERED);
 
 注意，列定义中的 `KEY` 和 `PRIMARY KEY` 含义相同。
 
-此外，TiDB 支持[可执行的注释语法](/comment-syntax.md)：
+此外，TiDB 支持使用[可执行的注释语法](/comment-syntax.md)指定聚簇索引属性：
 
 ```sql
 CREATE TABLE t (a BIGINT PRIMARY KEY /*T![clustered_index] CLUSTERED */, b VARCHAR(255)); 
@@ -59,6 +59,14 @@ CREATE TABLE t (a BIGINT, b VARCHAR(255), PRIMARY KEY(a, b) /*T![clustered_index
 CREATE TABLE t (a BIGINT, b VARCHAR(255), PRIMARY KEY(a, b) /*T![clustered_index] NONCLUSTERED */); 
 ```
 
+对于未显式指定该关键字的语句，默认行为受全局变量 `@@global.tidb_enable_clustered_index` 影响。该变量有三个取值：
+
+- `OFF` 表示所有主键默认使用非聚簇索引。
+- `ON` 表示所有主键默认使用聚簇索引。
+- `INT_ONLY` 此时的行为受配置项 `alter-primary-key` 控制。如果该配置项取值为 `true`，则所有主键默认使用非聚簇索引；如果该配置项取值为 `false`，则由单个整数类型的列构成的主键默认使用聚簇索引，其他类型的主键默认使用非聚簇索引。
+
+全局变量 `@@global.tidb_enable_clustered_index` 本身的默认值为 `INT_ONLY`。
+
 ### 添加、删除聚簇索引
 
 目前 TiDB 不支持在建表之后添加或删除聚簇索引，也不支持聚簇索引和非聚簇索引的互相转换。例如：

diff --git a/system-variables.md b/system-variables.md
@@ -430,20 +430,12 @@ mysql> SELECT * FROM t1;
 
 ### `tidb_enable_clustered_index` <span class="version-mark">从 v5.0.0-rc 版本开始引入</span>
 
-- 作用域：SESSION | GLOBAL
-- 默认值：OFF
-- 这个变量用于控制是否开启[聚簇索引](/clustered-indexes.md)特性。
-    - 该特性只适用于新创建的表，对于已经创建的旧表不会有影响。
-    - 该特性只适用于主键为单列非整数类型的表和主键为多列的表。对于无主键的表和主键是单列整数类型的表不会有影响。
-    - 通过执行 `select tidb_pk_type from information_schema.tables where table_name = '{table_name}'` 可以查看一张表是否使用了聚簇索引特性。
-- 特性启用以后，row 会直接存储在主键上，而不再是存储在系统内部分配的 `row_id` 上并用额外创建的主键索引指向 `row_id`。
-
-    开启该特性对性能的影响主要体现在以下几个方面:
-
-    - 插入的时候每行会减少一个索引 key 的写入。
-    - 使用主键作为等值条件查询的时候，会节省一次读取请求。
-    - 使用单列主键作为范围条件查询的时候，可以节省多次读取请求。
-    - 使用多列主键的前缀作为等值或范围条件查询的时候，可以节省多次读取请求。
+- 作用域：GLOBAL
+- 默认值：INT_ONLY
+- 这个变量用于控制默认情况下表的主键是否使用[聚簇索引](/clustered-indexes.md)。“默认情况”即不显式指定 `CLUSTERED`/`NONCLUSTERED` 关键字的情况。可设置为 `OFF`/`ON`/`INT_ONLY`。
+    - `OFF` 表示所有主键默认使用非聚簇索引。
+    - `ON` 表示所有主键默认使用聚簇索引。
+    - `INT_ONLY` 此时的行为受配置项 `alter-primary-key` 控制。如果该配置项取值为 `true`，则所有主键默认使用非聚簇索引；如果该配置项取值为 `false`，则由单个整数类型的列构成的主键默认使用聚簇索引，其他类型的主键默认使用非聚簇索引。
 
 ### `tidb_enable_collect_execution_info`
 

diff --git a/tidb-configuration-file.md b/tidb-configuration-file.md
@@ -98,7 +98,7 @@ TiDB 配置文件比命令行参数支持更多的选项。你可以在 [config/
 
 > **注意：**
 >
-> 该配置项不再生效。如果需要增删主键，请使用 `NONCLUSTERED` 代替。要了解关于 `CLUSTERED` 主键的详细信息，请参考[聚簇索引](/clustered-indexes.md)。
+> 该配置项已被废弃，目前仅在 `@@tidb_enable_clustered_index` 取值为 `INT_ONLY` 时生效。如果需要增删主键，请在建表时使用 `NONCLUSTERED` 关键字代替。要了解关于 `CLUSTERED` 主键的详细信息，请参考[聚簇索引](/clustered-indexes.md)。
 
 ### `server-version`