From 0dc998c6e78334b03dcbf05d528f0a718b728d6b Mon Sep 17 00:00:00 2001 From: ireneontheway <48651140+ireneontheway@users.noreply.github.com> Date: Mon, 13 Jul 2020 17:50:53 +0800 Subject: [PATCH 1/3] cherry pick #3238 to release-3.0 Signed-off-by: ti-srebot --- comment-syntax.md | 186 ++++++++++++++++++++++++++++++---------------- 1 file changed, 124 insertions(+), 62 deletions(-) diff --git a/comment-syntax.md b/comment-syntax.md index 3105daaa110bc..054c1c8eed674 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -1,76 +1,125 @@ --- title: Comment Syntax +<<<<<<< HEAD summary: Learn about the three comment styles in TiDB. category: reference aliases: ['/docs/v3.0/comment-syntax/','/docs/v3.0/reference/sql/language-structure/comment-syntax/','/docs/sql/comment-syntax/'] +======= +summary: This document introduces the comment syntax supported by TiDB. +aliases: ['/docs/dev/comment-syntax/','/docs/dev/reference/sql/language-structure/comment-syntax/'] +>>>>>>> 0af9946... comment-syntax: add TiDB-specific comment syntax (#3238) --- # Comment Syntax -TiDB supports three comment styles: +This document describes the comment syntax supported by TiDB. -- Use `#` to comment a line. -- Use `--` to comment a line, and this style requires at least one whitespace after `--`. -- Use `/* */` to comment a block or multiple lines. +TiDB supports three comment styles: -Example: +- Use `#` to comment a line: + + {{< copyable "sql" >}} + + ```sql + SELECT 1+1; # comments + ``` + + ``` + +------+ + | 1+1 | + +------+ + | 2 | + +------+ + 1 row in set (0.00 sec) + ``` + +- Use `--` to comment a line: + + {{< copyable "sql" >}} + + ```sql + SELECT 1+1; -- comments + ``` + + ``` + +------+ + | 1+1 | + +------+ + | 2 | + +------+ + 1 row in set (0.00 sec) + ``` + + And this style requires at least one whitespace after `--`: + + {{< copyable "sql" >}} + + ```sql + SELECT 1+1--1; + ``` + + ``` + +--------+ + | 1+1--1 | + +--------+ + | 3 | + +--------+ + 1 row in set (0.01 sec) + ``` + +- Use `/* */` to comment a block or multiple lines: + + {{< copyable "sql" >}} + + ```sql + SELECT 1 /* this is an in-line comment */ + 1; + ``` + + ``` + +--------+ + | 1 + 1 | + +--------+ + | 2 | + +--------+ + 1 row in set (0.01 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + SELECT 1+ + -> /* + /*> this is a + /*> multiple-line comment + /*> */ + -> 1; + ``` + + ``` + +-------+ + | 1+ + 1 | + +-------+ + | 2 | + +-------+ + 1 row in set (0.00 sec) + ``` + +## MySQL-compatible comment syntax + +The same as MySQL, TiDB supports a variant of C comment style: -```sql -mysql> SELECT 1+1; # This comment continues to the end of line -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) - -mysql> SELECT 1+1; -- This comment continues to the end of line -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) - -mysql> SELECT 1 /* this is an in-line comment */ + 1; -+--------+ -| 1 + 1 | -+--------+ -| 2 | -+--------+ -1 row in set (0.01 sec) - -mysql> SELECT 1+ - -> /* - /*> this is a - /*> multiple-line comment - /*> */ - -> 1; -+-------+ -| 1+ - -1 | -+-------+ -| 2 | -+-------+ -1 row in set (0.00 sec) - -mysql> SELECT 1+1--1; -+--------+ -| 1+1--1 | -+--------+ -| 3 | -+--------+ -1 row in set (0.01 sec) +``` +/*! Specific code */ ``` -Similar to MySQL, TiDB supports a variant of C comment style: +or ``` -/*! Specific code */ +/*!50110 Specific code */ ``` -In this comment style, TiDB runs the statements in the comment. The syntax is used to make these SQL statements ignored in other databases and run only in TiDB. +In this style, TiDB runs the statements in the comment. For example: @@ -84,20 +133,33 @@ In TiDB, you can also use another version: SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ... ``` +<<<<<<< HEAD If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment is processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the version number does not work and all contents in the comment are processed. +======= +If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment are processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number does not work and all contents in the comment are processed. +>>>>>>> 0af9946... comment-syntax: add TiDB-specific comment syntax (#3238) -Another type of comment is specially treated as the Hint optimizer: +## TiDB specific comment syntax -``` -SELECT /*+ hint */ FROM ...; -``` +TiDB has its own comment syntax (that is, TiDB specific comment syntax), which can be divided into the following two types: -Since Hint is involved in comments like `/*+ xxx */`, the MySQL client clears the comment by default in versions earlier than 5.7.7. To use Hint in those earlier versions, add the `--comments` option when you start the client. For example: +* `/*T! Specific code */`: This syntax can only be parsed and executed by TiDB, and be ignored in other databases. +* `/*T![feature_id] Specific code */`: This syntax is used to ensure compatibility between different versions of TiDB. TiDB can parse the SQL fragment in this comment only if it implements the corresponding feature of `feature_id` in the current version. For example, as the `AUTO_RANDOM` feature is introduced in v3.1.1, this version of TiDB can parse `/*T![auto_rand] auto_random */` into `auto_random`. Because the `AUTO_RANDOM` feature is not implemented in v3.0.0, the SQL statement fragment above is ignored. -``` -mysql -h 127.0.0.1 -P 4000 -uroot --comments +## Optimizer comment syntax + +Another type of comment is specially treated as an optimizer hint: + +{{< copyable "sql" >}} + +```sql +SELECT /*+ hint */ FROM ...; ``` For details about the optimizer hints that TiDB supports, see [Optimizer hints](/optimizer-hints.md). +> **Note** +> +> In MySQL client before 5.7.7, TiDB specific comment syntax and optimizer comment syntax are treated as comments and cleared by default. To use the two syntaxes in the old client, add the `--comments` option when you start the client. For example, `mysql -h 127.0.0.1 -P 4000 -uroot --comments`. + For more information, see [Comment Syntax](https://dev.mysql.com/doc/refman/5.7/en/comments.html). From 542dd5740a2c5655a8c4b6fe89916430aed9e69a Mon Sep 17 00:00:00 2001 From: Keke Yi <40977455+yikeke@users.noreply.github.com> Date: Mon, 13 Jul 2020 18:03:29 +0800 Subject: [PATCH 2/3] Update comment-syntax.md --- comment-syntax.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/comment-syntax.md b/comment-syntax.md index 054c1c8eed674..164cdf65aa2ac 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -1,13 +1,7 @@ --- title: Comment Syntax -<<<<<<< HEAD -summary: Learn about the three comment styles in TiDB. -category: reference -aliases: ['/docs/v3.0/comment-syntax/','/docs/v3.0/reference/sql/language-structure/comment-syntax/','/docs/sql/comment-syntax/'] -======= summary: This document introduces the comment syntax supported by TiDB. -aliases: ['/docs/dev/comment-syntax/','/docs/dev/reference/sql/language-structure/comment-syntax/'] ->>>>>>> 0af9946... comment-syntax: add TiDB-specific comment syntax (#3238) +aliases: ['/docs/v3.0/comment-syntax/','/docs/v3.0/reference/sql/language-structure/comment-syntax/','/docs/sql/comment-syntax/'] --- # Comment Syntax From 57f9d7d9e97a057fed9df642935b60c037a7d451 Mon Sep 17 00:00:00 2001 From: ireneontheway <48651140+ireneontheway@users.noreply.github.com> Date: Mon, 13 Jul 2020 19:29:41 +0800 Subject: [PATCH 3/3] Update comment-syntax.md remove changes from https://github.com/pingcap/docs-cn/pull/3477/files --- comment-syntax.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/comment-syntax.md b/comment-syntax.md index 164cdf65aa2ac..05fdade9a0c16 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -127,18 +127,11 @@ In TiDB, you can also use another version: SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ... ``` -<<<<<<< HEAD -If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment is processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the version number does not work and all contents in the comment are processed. -======= If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment are processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number does not work and all contents in the comment are processed. ->>>>>>> 0af9946... comment-syntax: add TiDB-specific comment syntax (#3238) ## TiDB specific comment syntax -TiDB has its own comment syntax (that is, TiDB specific comment syntax), which can be divided into the following two types: - -* `/*T! Specific code */`: This syntax can only be parsed and executed by TiDB, and be ignored in other databases. -* `/*T![feature_id] Specific code */`: This syntax is used to ensure compatibility between different versions of TiDB. TiDB can parse the SQL fragment in this comment only if it implements the corresponding feature of `feature_id` in the current version. For example, as the `AUTO_RANDOM` feature is introduced in v3.1.1, this version of TiDB can parse `/*T![auto_rand] auto_random */` into `auto_random`. Because the `AUTO_RANDOM` feature is not implemented in v3.0.0, the SQL statement fragment above is ignored. +TiDB has its own comment syntax (that is, TiDB specific comment syntax) with the format of `/*T![feature_id] XXX */`. TiDB can parse the SQL fragment in this comment only if it implements the corresponding feature of `feature_id` in the current version. For example, as the `AUTO_RANDOM` feature is introduced in v3.1.1, this version of TiDB can parse `/*T![auto_rand] auto_random */` into `auto_random`. Because the `AUTO_RANDOM` feature is not implemented in v3.0.0, the SQL statement fragment above is ignored. ## Optimizer comment syntax