Merge remote-tracking branch 'upstream/master' into cast_mv-17472

sql-statements/sql-statement-admin-show-ddl.md

@@ -78,13 +78,17 @@ OWNER_ADDRESS: 0.0.0.0:4000
 - `START_TIME`：DDL 操作的开始时间。
 - `END_TIME`：DDL 操作的结束时间。
 - `STATE`：DDL 操作的状态。常见的状态有以下几种：
-    - `queueing`：表示该操作任务已经进入 DDL 任务队列中，但尚未执行，因为还在排队等待前面的 DDL 任务完成。另一种原因可能是执行 `DROP` 操作后，会变为 `none` 状态，但是很快会更新为 `synced` 状态，表示所有 TiDB 实例都已经同步到该状态。
+    - `none`：表示该操作尚未开始。
+    - `queueing`：表示该操作任务已经进入 DDL 任务队列中，但尚未执行，因为还在排队等待前面的 DDL 任务完成。另一种原因可能是执行 `DROP` 操作后，`queueing` 状态会变为 `done` 状态，但是很快会更新为 `synced` 状态，表示所有 TiDB 实例都已经同步到该状态。
     - `running`：表示该操作正在执行。
     - `synced`：表示该操作已经执行成功，且所有 TiDB 实例都已经同步该状态。
     - `rollback done`：表示该操作执行失败，回滚完成。
     - `rollingback`：表示该操作执行失败，正在回滚。
     - `cancelling`：表示正在取消该操作。这个状态只有在用 [`ADMIN CANCEL DDL JOBS`](/sql-statements/sql-statement-admin-cancel-ddl.md) 命令取消 DDL 任务时才会出现。
+    - `cancelled`：表示该操作已经取消。
+    - `pausing`：表示正在暂停该操作。
     - `paused`：表示 DDL 已被暂停运行。这个状态只有在用 [`ADMIN PAUSED DDL JOBS`](/sql-statements/sql-statement-admin-pause-ddl.md) 命令暂停 DDL 任务时才会出现。可以通过 [`ADMIN RESUME DDL JOBS`](/sql-statements/sql-statement-admin-resume-ddl.md) 命令进行恢复运行。
+    - `done`：表示该操作在 TiDB owner 节点已经执行成功，但其他 TiDB 节点还没有同步该 DDL 任务所执行的变更。
 
 示例如下：
 

sql-statements/sql-statement-create-index.md

@@ -6,7 +6,7 @@ aliases: ['/docs-cn/dev/sql-statements/sql-statement-create-index/','/docs-cn/de
 
 # CREATE INDEX
 
-`CREATE INDEX` 语句用于在已有表中添加新索引，功能等同于 `ALTER TABLE .. ADD INDEX`。包含该语句提供了 MySQL 兼容性。
+`CREATE INDEX` 语句用于在已有表中添加新索引，功能等同于 [`ALTER TABLE .. ADD INDEX`](/sql-statements/sql-statement-alter-table.md)，提供了 MySQL 兼容性。
 
 ## 语法图
 
@@ -65,8 +65,6 @@ KeyOrIndex ::=
 
 ## 示例
 
-{{< copyable "sql" >}}
-
 ```sql
 CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL);
 ```
@@ -75,8 +73,6 @@ CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL);
 Query OK, 0 rows affected (0.10 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5);
 ```
@@ -86,8 +82,6 @@ Query OK, 5 rows affected (0.02 sec)
 Records: 5  Duplicates: 0  Warnings: 0
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 EXPLAIN SELECT * FROM t1 WHERE c1 = 3;
 ```
@@ -103,8 +97,6 @@ EXPLAIN SELECT * FROM t1 WHERE c1 = 3;
 3 rows in set (0.00 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 CREATE INDEX c1 ON t1 (c1);
 ```
@@ -113,8 +105,6 @@ CREATE INDEX c1 ON t1 (c1);
 Query OK, 0 rows affected (0.30 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 EXPLAIN SELECT * FROM t1 WHERE c1 = 3;
 ```
@@ -129,8 +119,6 @@ EXPLAIN SELECT * FROM t1 WHERE c1 = 3;
 2 rows in set (0.00 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 ALTER TABLE t1 DROP INDEX c1;
 ```
@@ -139,8 +127,6 @@ ALTER TABLE t1 DROP INDEX c1;
 Query OK, 0 rows affected (0.30 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 CREATE UNIQUE INDEX c1 ON t1 (c1);
 ```
@@ -153,28 +139,26 @@ Query OK, 0 rows affected (0.31 sec)
 
 在一些场景中，查询的条件往往是基于某个表达式进行过滤。在这些场景中，一般的索引不能生效，执行查询只能遍历整个表，导致查询性能较差。表达式索引是一种特殊的索引，能将索引建立于表达式上。在创建了表达式索引后，基于表达式的查询便可以使用上索引，极大提升查询的性能。
 
-假设要基于 `lower(col1)` 这个表达式建立索引，示例的 SQL 语句如下：
-
-{{< copyable "sql" >}}
+假设要基于 `LOWER(col1)` 这个表达式建立索引，示例的 SQL 语句如下：
 
 ```sql
-CREATE INDEX idx1 ON t1 ((lower(col1)));
+CREATE INDEX idx1 ON t1 ((LOWER(col1)));
 ```
 
 或者等价的语句：
 
-{{< copyable "sql" >}}
-
 ```sql
-ALTER TABLE t1 ADD INDEX idx1((lower(col1)));
+ALTER TABLE t1 ADD INDEX idx1((LOWER(col1)));
 ```
 
 还可以在建表的同时指定表达式索引：
 
-{{< copyable "sql" >}}
-
 ```sql
-CREATE TABLE t1(col1 char(10), col2 char(10), index((lower(col1))));
+CREATE TABLE t1 (
+    col1 CHAR(10),
+    col2 CHAR(10),
+    INDEX ((LOWER(col1)))
+);
 ```
 
 > **注意：**
@@ -183,8 +167,6 @@ CREATE TABLE t1(col1 char(10), col2 char(10), index((lower(col1))));
 
 删除表达式索引与删除普通索引的方法一致：
 
-{{< copyable "sql" >}}
-
 ```sql
 DROP INDEX idx1 ON t1;
 ```
@@ -194,10 +176,10 @@ DROP INDEX idx1 ON t1;
 > 表达式索引涉及众多表达式。为了确保正确性，当前仅允许经充分测试的一部分函数用于创建表达式索引，即生产环境中仅允许表达式中包含这些函数。这些函数可以通过查询变量 `tidb_allow_function_for_expression_index` 得到。在后续版本中，这些函数会持续增加。目前允许的函数如下: 
 > 
 > ```
-> json_array, json_array_append, json_array_insert, json_contains, json_contains_path, json_depth, json_extract, json_insert, json_keys, json_length, json_merge_patch, json_merge_preserve, json_object, json_pretty, json_quote, json_remove, json_replace, json_search, json_set, json_storage_size, json_type, json_unquote, json_valid, lower, md5, reverse, tidb_shard, upper, vitess_hash
+> JSON_ARRAY, JSON_ARRAY_APPEND, JSON_ARRAY_INSERT, JSON_CONTAINS, JSON_CONTAINS_PATH, JSON_DEPTH, JSON_EXTRACT, JSON_INSERT, JSON_KEYS, JSON_LENGTH, JSON_MERGE_PATCH, JSON_MERGE_PRESERVE, JSON_OBJECT, JSON_PRETTY, JSON_QUOTE, JSON_REMOVE, JSON_REPLACE, JSON_SEARCH, JSON_SET, JSON_STORAGE_SIZE, JSON_TYPE, JSON_UNQUOTE, JSON_VALID, LOWER, MD5, REVERSE, TIDB_SHARD, UPPER, VITESS_HASH
 > ```
 >
-> 对于以上列表之外的函数，由于未完成充分测试，当前仍为实验特性，不建议在生产环境中使用。其他的表达式例如运算符、`cast` 和 `case when` 也同样为实验特性，不建议在生产环境中使用。如果仍然希望使用，可以在 [TiDB 配置文件](/tidb-configuration-file.md#allow-expression-index-从-v400-版本开始引入)中进行以下设置：
+> 对于以上列表之外的函数，由于未完成充分测试，当前仍为实验特性，不建议在生产环境中使用。其他的表达式例如运算符、`CAST` 和 `CASE WHEN` 也同样为实验特性，不建议在生产环境中使用。如果仍然希望使用，可以在 [TiDB 配置文件](/tidb-configuration-file.md#allow-expression-index-从-v400-版本开始引入)中进行以下设置：
 >
 > ```sql
 > allow-expression-index = true
@@ -207,63 +189,55 @@ DROP INDEX idx1 ON t1;
 >
 > 表达式索引中的表达式不能包含以下内容：
 >
-> - 易变函数，例如 `rand()` 和 `now()` 等。
-> - 系统变量以及用户变量。
+> - 易变函数，例如 `RAND()` 和 `NOW()` 等。
+> - [系统变量](/system-variables.md)以及[用户变量](/user-defined-variables.md)。
 > - 子查询。
-> - AUTO_INCREMENT 属性的列。一个例外是设置系统变量 `tidb_enable_auto_increment_in_generated` 为 `true` 后，可以去掉该限制。
-> - 窗口函数。
-> - row 函数。例如 `create table t (j json, key k (((j,j))));`。
-> - 聚合函数。
-> 
+> - [`AUTO_INCREMENT`](/auto-increment.md) 属性的列。一个例外是设置系统变量 [`tidb_enable_auto_increment_in_generated`](/system-variables.md#tidb_enable_auto_increment_in_generated) 为 `true` 后，可以去掉该限制。
+> - [窗口函数](/functions-and-operators/window-functions.md)。
+> - ROW 函数。例如 `CREATE TABLE t (j JSON, INDEX k (((j,j))));`。
+> - [聚合函数](/functions-and-operators/aggregate-group-by-functions.md)。
+>
 > 表达式索引将隐式占用名字，`_V$_{index_name}_{index_offset}`，如果已有相同名字的列存在，创建表达式索引将报错。如果后续新增相同名字的列，也会报错。
 >
 > 在表达式索引中，表达式的函数参数个数必须正确。
-> 
-> 当索引的表达式使用了字符串相关的函数时，受返回类型以及其长度的影响，创建表达式索引可能会失败。这时可以使用 `cast()` 函数显式指定返回的类型以及长度。例如表达式 `repeat(a, 3)`，为了能根据该表达式建立表达式索引，需要将表达式改写为 `cast(repeat(a, 3) as char(20))` 这样的形式。
+>
+> 当索引的表达式使用了字符串相关的函数时，受返回类型以及其长度的影响，创建表达式索引可能会失败。这时可以使用 `CAST()` 函数显式指定返回的类型以及长度。例如表达式 `REPEAT(a, 3)`，为了能根据该表达式建立表达式索引，需要将表达式改写为 `CAST(REPEAT(a, 3) AS CHAR(20))` 这样的形式。
 
 当查询语句中的表达式与表达式索引中的表达式一致时，优化器可以为该查询选择使用表达式索引。依赖于统计信息，某些情况下优化器不一定选择表达式索引。这时可以通过 hint 指定强制使用表达式索引。
 
-在以下示例中，假设建立在 `lower(col1)` 表达式上的索引为 `idx`。
+在以下示例中，假设建立在 `LOWER(col1)` 表达式上的索引为 `idx`。
 
 当读取的结果为相同的表达式时，可以使用表达式索引。例如：
 
-{{< copyable "sql" >}}
-
 ```sql
-SELECT lower(col1) FROM t;
+SELECT LOWER(col1) FROM t;
 ```
 
 当过滤的条件中有相同的表达式时，可以使用表达式索引。例如：
 
-{{< copyable "sql" >}}
-
 ```sql
-SELECT * FROM t WHERE lower(col1) = "a";
-SELECT * FROM t WHERE lower(col1) > "a";
-SELECT * FROM t WHERE lower(col1) BETWEEN "a" AND "b";
-SELECT * FROM t WHERE lower(col1) in ("a", "b");
-SELECT * FROM t WHERE lower(col1) > "a" AND lower(col1) < "b";
-SELECT * FROM t WHERE lower(col1) > "b" OR lower(col1) < "a";
+SELECT * FROM t WHERE LOWER(col1) = "a";
+SELECT * FROM t WHERE LOWER(col1) > "a";
+SELECT * FROM t WHERE LOWER(col1) BETWEEN "a" AND "b";
+SELECT * FROM t WHERE LOWER(col1) IN ("a", "b");
+SELECT * FROM t WHERE LOWER(col1) > "a" AND LOWER(col1) < "b";
+SELECT * FROM t WHERE LOWER(col1) > "b" OR LOWER(col1) < "a";
 ```
 
 当查询按照相同的表达式进行排序时，可以使用表达式索引。例如：
 
-{{< copyable "sql" >}}
-
 ```sql
-SELECT * FROM t ORDER BY lower(col1);
+SELECT * FROM t ORDER BY LOWER(col1);
 ```
 
 当聚合函数或者 `GROUP BY` 中包含相同的表达式时，可以使用表达式索引。例如：
 
-{{< copyable "sql" >}}
-
 ```sql
-SELECT max(lower(col1)) FROM t;
-SELECT min(col1) FROM t GROUP BY lower(col1);
+SELECT MAX(LOWER(col1)) FROM t;
+SELECT MIN(col1) FROM t GROUP BY LOWER(col1);
 ```
 
-要查看表达式索引对应的表达式，可执行 `show index` 或查看系统表 `information_schema.tidb_indexes` 以及 `information_schema.STATISTICS` 表，输出中 `Expression` 这一列显示对应的表达式。对于非表达式索引，该列的值为 `NULL`。
+要查看表达式索引对应的表达式，可执行 [`SHOW INDEX`](/sql-statements/sql-statement-show-indexes.md) 或查看系统表 [`information_schema.tidb_indexes`](/information-schema/information-schema-tidb-indexes.md) 以及 [`information_schema.STATISTICS`](/information-schema/information-schema-statistics.md) 表，输出中 `Expression` 这一列显示对应的表达式。对于非表达式索引，该列的值为 `NULL`。
 
 维护表达式索引的代价比一般的索引更高，因为在插入或者更新每一行时都需要计算出表达式的值。因为表达式的值已经存储在索引中，所以当优化器选择表达式索引时，表达式的值就不需要再计算。因此，当查询速度比插入速度和更新速度更重要时，可以考虑建立表达式索引。
 

ticdc/ticdc-changefeed-config.md

@@ -208,6 +208,8 @@ enable-partition-separator = true
 # 是否输出 handle 列信息。默认值为 false。该配置项仅用于内部实现，不推荐设置该配置项。
 # output-handle-key = false
 # 是否输出行数据更改前的值。默认值为 false。开启后，Update 事件会输出两行数据：第一行为 Delete 事件，输出更改前的数据；第二行为 Insert 事件，输出更改后的数据。
+# 开启后，即当该参数设为 true 时，会在变更数据列前增加 "is-update" 列。该列用来标识当前行的变更数据是来自 Update 事件，还是原始的 Insert/Delete 事件。
+# 如果当前行的变更数据来自 Update 事件，则 "is-update" 列为 true，否则为 false。
 # output-old-value = false
 
 # 从 v8.0.0 开始，TiCDC 新增了 Simple Protocol 消息编码协议，以下为该协议的配置参数。

ticdc/ticdc-csv.md

@@ -28,6 +28,7 @@ quote = '"'
 null = '\N'
 include-commit-ts = true
 binary-encoding-method = 'base64'
+output-old-value = false
 ```
 
 ## 数据保存的事务性约束
@@ -48,7 +49,8 @@ CSV 文件中，单行的每一列定义如下：
 - 第二列：表名。
 - 第三列：库名。
 - 第四列：`commit ts`，即原始事务的 commit ts。该列为可选配置。
-- 第五列至最后一列：变更数据的列，可为一列或多列。
+- 第五列：`is-update`，该列仅在 `output-old-value` 为 true 时存在，用于标识该行变更来自 Update 事件（值为 true），还是来自 Insert/Delete 事件（值为 false）。
+- 第六列至最后一列：变更数据的列，可为一列或多列。
 
 假设某张表 `hr.employee` 的定义如下：
 
@@ -62,7 +64,7 @@ CREATE TABLE `employee` (
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
 ```
 
-该表上的 DML 事件以 CSV 格式存储后如下所示：
+当配置中 `include-commit-ts = true` 且 `output-old-value = false` 时，该表上的 DML 事件以 CSV 格式存储后如下所示：
 
 ```
 "I","employee","hr",433305438660591626,101,"Smith","Bob","2014-06-04","New York"
@@ -72,6 +74,18 @@ CREATE TABLE `employee` (
 "U","employee","hr",433305438660591630,102,"Alex","Alice","2018-06-15","Beijing"
 ```
 
+当配置中 `include-commit-ts = true` 且 `output-old-value = true` 时，该表上的 DML 事件以 CSV 格式存储后如下所示：
+
+```
+"I","employee","hr",433305438660591626,false,101,"Smith","Bob","2014-06-04","New York"
+"D","employee","hr",433305438660591627,true,101,"Smith","Bob","2015-10-08","Shanghai"
+"I","employee","hr",433305438660591627,true,101,"Smith","Bob","2015-10-08","Los Angeles"
+"D","employee","hr",433305438660591629,false,101,"Smith","Bob","2017-03-13","Dallas"
+"I","employee","hr",433305438660591630,false,102,"Alex","Alice","2017-03-14","Shanghai"
+"D","employee","hr",433305438660591630,true,102,"Alex","Alice","2017-03-14","Beijing"
+"I","employee","hr",433305438660591630,true,102,"Alex","Alice","2018-06-15","Beijing"
+```
+
 ## 数据类型映射
 
 | MySQL 类型                                                          | CSV 类型  | 示例                             | 描述                            |