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.

User-Defined Variables - 图1

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. 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 connection cannot be seen or used by other client connections.

Set the user-defined variables

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:

  1. SET @favorite_db = 'TiDB';
  1. SET @a = 'a', @b = 'b', @c = 'c';

For the assignment operator, you can also use :=. For example:

  1. SET @favorite_db := 'TiDB';

The content to the right of the assignment operator can be any valid expression. For example:

  1. SET @c = @a + @b;
  1. 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:

  1. SELECT @a1, @a2, @a3
  1. +------+------+------+
  2. | @a1 | @a2 | @a3 |
  3. +------+------+------+
  4. | 1 | 2 | 4 |
  5. +------+------+------+

You can also assign values in the SELECT statement:

  1. SELECT @a1, @a2, @a3, @a4 := @a1+@a2+@a3;
  1. +------+------+------+--------------------+
  2. | @a1 | @a2 | @a3 | @a4 := @a1+@a2+@a3 |
  3. +------+------+------+--------------------+
  4. | 1 | 2 | 4 | 7 |
  5. +------+------+------+--------------------+

Before the variable @a4 is modified or the connection is closed, its value is always 7.

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:

  1. SET @v1 = b'1000001';
  2. SET @v2 = b'1000001'+0;
  3. SET @v3 = CAST(b'1000001' AS UNSIGNED);
  1. SELECT @v1, @v2, @v3;
  1. +------+------+------+
  2. | @v1 | @v2 | @v3 |
  3. +------+------+------+
  4. | A | 65 | 65 |
  5. +------+------+------+

If you refer to a user-defined variable that has not been initialized, it has a value of NULL and a type of string.

  1. SELECT @not_exist;
  1. +------------+
  2. | @not_exist |
  3. +------------+
  4. | NULL |
  5. +------------+

In addition to using the SELECT statement to read the user-defined variables, another common usage is the PREPARE statement. For example:

  1. SET @s = 'SELECT SQRT(POW(?,2) + POW(?,2)) AS hypotenuse';
  2. PREPARE stmt FROM @s;
  3. SET @a = 6;
  4. SET @b = 8;
  5. EXECUTE stmt USING @a, @b;
  1. +------------+
  2. | hypotenuse |
  3. +------------+
  4. | 10 |
  5. +------------+

The contents of the user-defined variables are not recognized as identifiers in the SQL statements. For example:

  1. SELECT * from t;
  1. +---+
  2. | a |
  3. +---+
  4. | 1 |
  5. +---+
  1. SET @col = "`a`";
  2. SELECT @col FROM t;
  1. +------+
  2. | @col |
  3. +------+
  4. | `a` |
  5. +------+

MySQL compatibility

Except for SELECT ... INTO <variable>, the syntax supported in MySQL and TiDB is identical.

For more information, see User-Defined Variables in MySQL.