From c0130978e88efae240a308f5ff09f6238d2163dd Mon Sep 17 00:00:00 2001 From: tangenta Date: Mon, 25 May 2020 18:22:37 +0800 Subject: [PATCH 1/4] cherry pick #3193 to release-3.1 Signed-off-by: sre-bot --- auto-random.md | 8 +- comment-syntax.md | 205 ++++++++++++++++++++++++++-------------------- 2 files changed, 124 insertions(+), 89 deletions(-) diff --git a/auto-random.md b/auto-random.md index 113fef4166c1..187ca20dfac6 100644 --- a/auto-random.md +++ b/auto-random.md @@ -114,7 +114,11 @@ TiDB 支持解析版本注释语法。示例如下： {{< copyable "sql" >}} ```sql +<<<<<<< HEAD create table t (a int primary key /*T!30100 auto_random */) +======= +create table t (a bigint primary key /*T![auto_rand] auto_random */) +>>>>>>> cd61a4c... update comment-syntax.md (#3193) ``` {{< copyable "sql" >}} @@ -125,9 +129,9 @@ create table t (a int primary key auto_random) 以上两个语句含义相同。 -在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个版本号，例如 `/*T!30100 auto_random */`。其中 `30100` 表示 v3.1.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释的 `AUTO_RANDOM` 属性。 +在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个特性标识符，例如 `/*T![auto_rand] auto_random */`。其中 `auto_rand` 表示 `AUTO_RANDOM` 的特性标识符，只有实现了该标识符对应特性的 TiDB 版本才能够正常解析 SQL 语句片段。 -该功能支持向前兼容，即降级兼容。v3.1.0 以前的 TiDB 会忽略表（带有上述注释）的 `AUTO_RANDOM` 属性，因此能够使用含有该属性的表。 +该功能支持向前兼容，即降级兼容。没有实现对应特性的 TiDB 版本则会忽略表（带有上述注释）的 `AUTO_RANDOM` 属性，因此能够使用含有该属性的表。 ## 使用限制 diff --git a/comment-syntax.md b/comment-syntax.md index b8e0eab7ac74..8cafead5dd67 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -1,105 +1,122 @@ --- title: 注释语法 category: reference +<<<<<<< HEAD aliases: ['/docs-cn/v3.1/reference/sql/language-structure/comment-syntax/'] +======= +summary: 本文介绍 TiDB 支持的注释语法。 +aliases: ['/docs-cn/dev/reference/sql/language-structure/comment-syntax/'] +>>>>>>> cd61a4c... update comment-syntax.md (#3193) --- # 注释语法 -TiDB 支持三种注释风格： - -* 用 `#` 注释一行 -* 用 `--` 注释一行，用 `--` 注释必须要在其之后留出至少一个空格。 -* 用 `/* */` 注释一块，可以注释多行。 - -例： - -{{< copyable "sql" >}} - -```sql -SELECT 1+1; # 注释文字 -``` - -``` -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1+1; -- 注释文字 -``` - -``` -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1 /* 这是行内注释文字 */ + 1; -``` - -``` -+--------+ -| 1 + 1 | -+--------+ -| 2 | -+--------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} +本文档介绍 TiDB 支持的注释语法。 -```sql -SELECT 1+ - -> /* - /*> 这是一条 - /*> 多行注释 - /*> */ - -> 1; -``` +TiDB 支持三种注释风格： -``` -+-------+ -| 1+ - -1 | -+-------+ -| 2 | -+-------+ -1 row in set (0.00 sec) -``` +* 用 `#` 注释一行： + + {{< copyable "sql" >}} + + ```sql + SELECT 1+1; # 注释文字 + ``` + + ``` + +------+ + | 1+1 | + +------+ + | 2 | + +------+ + 1 row in set (0.00 sec) + ``` + +* 用 `--` 注释一行： + + {{< copyable "sql" >}} + + ```sql + SELECT 1+1; -- 注释文字 + ``` + + ``` + +------+ + | 1+1 | + +------+ + | 2 | + +------+ + 1 row in set (0.00 sec) + ``` + + 用 `--` 注释时，必须要在其之后留出至少一个空格，否则注释不生效： + + {{< copyable "sql" >}} + + ```sql + SELECT 1+1--1; + ``` + + ``` + +--------+ + | 1+1--1 | + +--------+ + | 3 | + +--------+ + 1 row in set (0.01 sec) + ``` + +* 用 `/* */` 注释一块，可以注释多行： + + {{< copyable "sql" >}} + + ```sql + SELECT 1 /* 这是行内注释文字 */ + 1; + ``` + + ``` + +--------+ + | 1 + 1 | + +--------+ + | 2 | + +--------+ + 1 row in set (0.01 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + SELECT 1+ + -> /* + /*> 这是一条 + /*> 多行注释 + /*> */ + -> 1; + ``` + + ``` + +-------+ + | 1+ + + 1 | + +-------+ + | 2 | + +-------+ + 1 row in set (0.00 sec) + ``` + +## MySQL 兼容的注释语法 -{{< copyable "sql" >}} - -```sql -SELECT 1+1--1; -``` +TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： ``` -+--------+ -| 1+1--1 | -+--------+ -| 3 | -+--------+ -1 row in set (0.01 sec) +/*! Specific code */ ``` -TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： +或者 ``` -/*! Specific code */ +/*!50110 Specific code */ ``` 在这种格式中，TiDB 会执行注释中的语句，这个语法是为了让这些 SQL 在其他的数据库中被忽略，而在 TiDB 中被执行。 @@ -108,7 +125,13 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： 在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` -如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个 MySQL 版本号不会起作用，所有的 comment 都被会处理。TiDB 有自己的版本号注释语法，格式为 `/*T!30100 XXX */`。 +如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个 MySQL 版本号不会起作用，所有的 comment 都被会处理。 + +## TiDB 可执行的注释语法 + +TiDB 也有独立的注释语法，称为 TiDB 可执行注释语法，格式为 `/*T![feature_id] XXX */`。只有在当前版本中实现了 `feature_id` 对应的功能特性的 TiDB，才会试图解析该注释里的 SQL 片段。例如 v3.1.1 中引入了 `AUTO_RANDOM` 特性，该版本能够将 `/*T![auto_rand] auto_random */` 解析为 `auto_random`；而 v3.0.0 中没有实现 `AUTO_RANDOM` 特性，则上述 SQL 语句片段会被忽略。 + +## 优化器注释语法 还有一种注释会被当做是优化器 Hint 特殊对待： @@ -118,8 +141,16 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： SELECT /*+ hint */ FROM ...; ``` +<<<<<<< HEAD 由于 hint 包含在类似 /*+ xxx */ 的 comment 里，MySQL 客户端在 5.7.7 之前，会默认把 comment 清除掉，如果需要在旧的客户端使用 hint，需要在启动客户端时加上 --comments 选项，例如 mysql -h 127.0.0.1 -P 4000 -uroot --comments TiDB 支持的相关优化器 hint 详见 [Optimizer Hints](/optimizer-hints.md) +======= +TiDB 支持的相关优化器 hint 详见 [Optimizer Hints](/optimizer-hints.md)。 +>>>>>>> cd61a4c... update comment-syntax.md (#3193) + +> **注意** +> +> 由于 TiDB 可执行注释语法和优化器注释语法在 MySQL 客户端 5.7.7 之前的版本中，会被默认当成 comment 清除掉，如果需要在旧的客户端使用这两种语法，需要在启动客户端时加上 --comments 选项，例如 `mysql -h 127.0.0.1 -P 4000 -uroot --comments`。 -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/comments.html)。 +更多细节，请参考 [MySQL 文档](https://dev.mysql.com/doc/refman/5.7/en/comments.html)。 From eeac2c0c76543cbec09d9e96ff9d5eae1fc97927 Mon Sep 17 00:00:00 2001 From: Ran Date: Fri, 12 Jun 2020 16:36:25 +0800 Subject: [PATCH 2/4] resolve conflict --- comment-syntax.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/comment-syntax.md b/comment-syntax.md index 8cafead5dd67..dd46f1fb2322 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -1,12 +1,8 @@ --- title: 注释语法 category: reference -<<<<<<< HEAD -aliases: ['/docs-cn/v3.1/reference/sql/language-structure/comment-syntax/'] -======= summary: 本文介绍 TiDB 支持的注释语法。 -aliases: ['/docs-cn/dev/reference/sql/language-structure/comment-syntax/'] ->>>>>>> cd61a4c... update comment-syntax.md (#3193) +aliases: ['/docs-cn/v3.1/reference/sql/language-structure/comment-syntax/'] --- # 注释语法 From 105784dec2762ff736a125f5f12c7e5e81bfeeb2 Mon Sep 17 00:00:00 2001 From: Ran Date: Fri, 12 Jun 2020 17:02:46 +0800 Subject: [PATCH 3/4] Update auto-random.md --- auto-random.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/auto-random.md b/auto-random.md index 187ca20dfac6..f4c264989b07 100644 --- a/auto-random.md +++ b/auto-random.md @@ -114,11 +114,7 @@ TiDB 支持解析版本注释语法。示例如下： {{< copyable "sql" >}} ```sql -<<<<<<< HEAD -create table t (a int primary key /*T!30100 auto_random */) -======= create table t (a bigint primary key /*T![auto_rand] auto_random */) ->>>>>>> cd61a4c... update comment-syntax.md (#3193) ``` {{< copyable "sql" >}} From cf686e372eb2fd72294f4f3d0a12f9283de46021 Mon Sep 17 00:00:00 2001 From: Ran Date: Fri, 12 Jun 2020 17:03:57 +0800 Subject: [PATCH 4/4] Update comment-syntax.md --- comment-syntax.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/comment-syntax.md b/comment-syntax.md index dd46f1fb2322..dff3d718f1c9 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -137,13 +137,7 @@ TiDB 也有独立的注释语法，称为 TiDB 可执行注释语法，格式为 SELECT /*+ hint */ FROM ...; ``` -<<<<<<< HEAD -由于 hint 包含在类似 /*+ xxx */ 的 comment 里，MySQL 客户端在 5.7.7 之前，会默认把 comment 清除掉，如果需要在旧的客户端使用 hint，需要在启动客户端时加上 --comments 选项，例如 mysql -h 127.0.0.1 -P 4000 -uroot --comments - -TiDB 支持的相关优化器 hint 详见 [Optimizer Hints](/optimizer-hints.md) -======= TiDB 支持的相关优化器 hint 详见 [Optimizer Hints](/optimizer-hints.md)。 ->>>>>>> cd61a4c... update comment-syntax.md (#3193) > **注意** >