From 0d74ce434ffe5be6e9da69508adbd88e53174de3 Mon Sep 17 00:00:00 2001 From: DanielZhangQD Date: Sun, 28 Jun 2020 20:21:22 +0800 Subject: [PATCH 1/3] update doc for user-defined variables --- user-defined-variables.md | 185 +++++++++++++++++++++++--------------- 1 file changed, 114 insertions(+), 71 deletions(-) diff --git a/user-defined-variables.md b/user-defined-variables.md index 5e2a62d4b90cb..e6987ac6e2e49 100644 --- a/user-defined-variables.md +++ b/user-defined-variables.md @@ -7,134 +7,177 @@ aliases: ['/docs/dev/user-defined-variables/','/docs/dev/reference/sql/language- # User-Defined Variables +This document describes the concept of user-defined variables of TiDB and the methods to set and read the user-defined variables. + > **Warning:** > > User-defined variables are still an experimental feature. It is **NOT** recommended that you use them in the production environment. -The format of the user-defined variables is `@var_name`. `@var_name` consists of alphanumeric characters, `_`, and `$`. The user-defined variables are case-insensitive. +The format of the user-defined variables is `@var_name`. The characters that compose `var_name` can be any characters that can compose an identifier, including the numbers `0-9`, the letters `a-zA-Z`, the underscore `_`, the dollar sign `$`, and the UTF-8 characters. In addition, it also includes the English period `.`. The user-defined variables are case-insensitive. + +The user-defined variables are session specific, which means a user variable defined by one client cannot be seen or used by other clients connections. + +## Set the user-defined variables -The user-defined variables are session specific, which means a user variable defined by one client cannot be seen or used by other clients. +You can use the `SET` statement to set a user-defined variable, and the syntax is `SET @var_name = expr [, @var_name = expr] ...;`. For example: -You can use the `SET` statement to set a user variable: +{{< copyable "sql" >}} ```sql -SET @var_name = expr [, @var_name = expr] ... +SET @favorite_db = 'TiDB'; ``` -or +{{< copyable "sql" >}} ```sql -SET @var_name := expr +SET @a = 'a', @b = 'b', @c = 'c'; ``` -For `SET`, you can use `=` or `:=` as the assignment operator. +For the assignment operator, you can also use `:=`. For example: -For example: +{{< copyable "sql" >}} ```sql -mysql> SET @a1=1, @a2=2, @a3:=4; -mysql> SELECT @a1, @a2, @t3, @a4 := @a1+@a2+@a3; -+------+------+------+--------------------+ -| @a1 | @a2 | @a3 | @a4 := @a1+@a2+@a3 | -+------+------+------+--------------------+ -| 1 | 2 | 4 | 7 | -+------+------+------+--------------------+ +SET @favorite_db = 'TiDB'; ``` -Hexadecimal or bit values assigned to user variables are treated as binary strings in TiDB. To assign a hexadecimal or bit value as a number, use it in numeric context. For example, add `0` or use `CAST(... AS UNSIGNED)`: +The content to the right of the assignment operator can be any legal expression. For example: + +{{< copyable "sql" >}} ```sql -mysql> SELECT @v1, @v2, @v3; +SET @c = @a + @b; +``` + +{{< copyable "sql" >}} + +```sql +set @c = b'1000001' + b'1000001'; +``` + +## Read the user-defined variables + +To read a user-defined variable, you can use the `SELECT` statement to query: + +{{< copyable "sql" >}} + +```sql +SELECT @a1, @a2, @t3 +``` + +``` +------+------+------+ -| @v1 | @v2 | @v3 | +| @a1 | @a2 | @a3 | +------+------+------+ -| A | 65 | 65 | +| 1 | 2 | 4 | +------+------+------+ -1 row in set (0.00 sec) +``` + +You can also assign values in the `SELECT` statement: + +```sql +SELECT @a1, @a2, @t3, @a4 := @a1+@a2+@a3; +``` + +``` ++------+------+------+--------------------+ +| @a1 | @a2 | @a3 | @a4 := @a1+@a2+@a3 | ++------+------+------+--------------------+ +| 1 | 2 | 4 | 7 | ++------+------+------+--------------------+ +``` -mysql> SET @v1 = b'1000001'; -Query OK, 0 rows affected (0.00 sec) +Before the variable `@a4` is modified or the connection is closed, its value is always `7`。 -mysql> SET @v2 = b'1000001'+0; -Query OK, 0 rows affected (0.00 sec) +If a hexadecimal literal or binary literal is used when setting the user-defined variable, TiDB will treat it as a binary string. If you want to set it to a number, you can manually add the `CAST` conversion, or use the numeric operator in the expression: -mysql> SET @v3 = CAST(b'1000001' AS UNSIGNED); -Query OK, 0 rows affected (0.00 sec) +{{< copyable "sql" >}} + +```sql +SET @v1 = b'1000001'; +SET @v2 = b'1000001'+0; +SET @v3 = CAST(b'1000001' AS UNSIGNED); +``` + +{{< copyable "sql" >}} + +```sql +SELECT @v1, @v2, @v3; +``` -mysql> SELECT @v1, @v2, @v3; +``` +------+------+------+ -| @v1 | @v2 | @v3 | +| @v1 | @v2 | @v3 | +------+------+------+ -| A | 65 | 65 | +| A | 65 | 65 | +------+------+------+ -1 row in set (0.00 sec) ``` If you refer to a user-defined variable that has not been initialized, it has a value of NULL and a type of string. +{{< copyable "sql" >}} + ```sql -mysql> select @not_exist; +SELECT @not_exist; +``` + +``` +------------+ | @not_exist | +------------+ -| NULL | +| NULL | +------------+ -1 row in set (0.00 sec) ``` -The user-defined variables cannot be used as an identifier in the SQL statement. For example: +In addition to the `SELECT` statement to read the user-defined variables, another common usage is the `PREPARE` statement. For example: + +{{< copyable "sql" >}} ```sql -mysql> select * from t; -+------+ -| a | -+------+ -| 1 | -+------+ -1 row in set (0.00 sec) +SET @s = 'SELECT SQRT(POW(?,2) + POW(?,2)) AS hypotenuse'; +PREPARE stmt FROM @s; +SET @a = 6; +SET @b = 8; +EXECUTE stmt USING @a, @b; +``` -mysql> SET @col = "a"; -Query OK, 0 rows affected (0.00 sec) +``` ++------------+ +| hypotenuse | ++------------+ +| 10 | ++------------+ +``` -mysql> SELECT @col FROM t; -+------+ -| @col | -+------+ -| a | -+------+ -1 row in set (0.00 sec) +The user-defined variables will not be used as identifiers in SQL statements. For example: -mysql> SELECT `@col` FROM t; -ERROR 1054 (42S22): Unknown column '@col' in 'field list' +{{< copyable "sql" >}} -mysql> SET @col = "`a`"; -Query OK, 0 rows affected (0.00 sec) +```sql +SELECT * from t; +``` -mysql> SELECT @col FROM t; -+------+ -| @col | -+------+ -| `a` | -+------+ -1 row in set (0.01 sec) +``` ++---+ +| a | ++---+ +| 1 | ++---+ ``` -An exception is that when you are constructing a string for use as a prepared statement to execute later: +{{< copyable "sql" >}} ```sql -mysql> PREPARE stmt FROM "SELECT @c FROM t"; -Query OK, 0 rows affected (0.00 sec) +SET @col = "`a`"; +SELECT @col FROM t; +``` -mysql> EXECUTE stmt; +``` +------+ -| @c | +| @col | +------+ -| a | +| `a` | +------+ -1 row in set (0.01 sec) - -mysql> DEALLOCATE PREPARE stmt; -Query OK, 0 rows affected (0.00 sec) ``` For more information, see [User-Defined Variables in MySQL](https://dev.mysql.com/doc/refman/5.7/en/user-variables.html). From 7a4f79dbb39ab37b617097a9a0b39440a96e14d4 Mon Sep 17 00:00:00 2001 From: DanielZhangQD Date: Sun, 28 Jun 2020 20:51:30 +0800 Subject: [PATCH 2/3] update wording --- user-defined-variables.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user-defined-variables.md b/user-defined-variables.md index e6987ac6e2e49..54899e15b5436 100644 --- a/user-defined-variables.md +++ b/user-defined-variables.md @@ -15,7 +15,7 @@ This document describes the concept of user-defined variables of TiDB and the me The format of the user-defined variables is `@var_name`. The characters that compose `var_name` can be any characters that can compose an identifier, including the numbers `0-9`, the letters `a-zA-Z`, the underscore `_`, the dollar sign `$`, and the UTF-8 characters. In addition, it also includes the English period `.`. The user-defined variables are case-insensitive. -The user-defined variables are session specific, which means a user variable defined by one client cannot be seen or used by other clients connections. +The user-defined variables are session-specific, which means a user variable defined by one client connection cannot be seen or used by other client connections. ## Set the user-defined variables @@ -149,7 +149,7 @@ EXECUTE stmt USING @a, @b; +------------+ ``` -The user-defined variables will not be used as identifiers in SQL statements. For example: +The contents of the user-defined variables will not be used as identifiers in the SQL statements. For example: {{< copyable "sql" >}} From b63ee2971c0d6519ae551b5f13ce0e8794495e62 Mon Sep 17 00:00:00 2001 From: DanielZhangQD <36026334+DanielZhangQD@users.noreply.github.com> Date: Tue, 30 Jun 2020 11:44:00 +0800 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Ran --- user-defined-variables.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/user-defined-variables.md b/user-defined-variables.md index 54899e15b5436..210568501f85c 100644 --- a/user-defined-variables.md +++ b/user-defined-variables.md @@ -7,7 +7,7 @@ aliases: ['/docs/dev/user-defined-variables/','/docs/dev/reference/sql/language- # User-Defined Variables -This document describes the concept of user-defined variables of TiDB and the methods to set and read the user-defined variables. +This document describes the concept of user-defined variables in TiDB and the methods to set and read the user-defined variables. > **Warning:** > @@ -38,10 +38,10 @@ For the assignment operator, you can also use `:=`. For example: {{< copyable "sql" >}} ```sql -SET @favorite_db = 'TiDB'; +SET @favorite_db := 'TiDB'; ``` -The content to the right of the assignment operator can be any legal expression. For example: +The content to the right of the assignment operator can be any valid expression. For example: {{< copyable "sql" >}} @@ -62,7 +62,7 @@ To read a user-defined variable, you can use the `SELECT` statement to query: {{< copyable "sql" >}} ```sql -SELECT @a1, @a2, @t3 +SELECT @a1, @a2, @a3 ``` ``` @@ -76,7 +76,7 @@ SELECT @a1, @a2, @t3 You can also assign values in the `SELECT` statement: ```sql -SELECT @a1, @a2, @t3, @a4 := @a1+@a2+@a3; +SELECT @a1, @a2, @a3, @a4 := @a1+@a2+@a3; ``` ``` @@ -129,7 +129,7 @@ SELECT @not_exist; +------------+ ``` -In addition to the `SELECT` statement to read the user-defined variables, another common usage is the `PREPARE` statement. For example: +In addition to using the `SELECT` statement to read the user-defined variables, another common usage is the `PREPARE` statement. For example: {{< copyable "sql" >}} @@ -149,7 +149,7 @@ EXECUTE stmt USING @a, @b; +------------+ ``` -The contents of the user-defined variables will not be used as identifiers in the SQL statements. For example: +The contents of the user-defined variables are not recognized as identifiers in the SQL statements. For example: {{< copyable "sql" >}}