From c18bbfda99706908dcb331e6e6667fb06bd51845 Mon Sep 17 00:00:00 2001 From: en-jin19 Date: Thu, 26 Aug 2021 10:47:08 +0200 Subject: [PATCH 1/5] docs: fix expression index's document again --- sql-statements/sql-statement-create-index.md | 31 +++++++++++++++++--- system-variables.md | 5 ++++ tidb-configuration-file.md | 9 ++++++ 3 files changed, 41 insertions(+), 4 deletions(-) diff --git a/sql-statements/sql-statement-create-index.md b/sql-statements/sql-statement-create-index.md index a713e9f48c828..8e53c709657f0 100644 --- a/sql-statements/sql-statement-create-index.md +++ b/sql-statements/sql-statement-create-index.md @@ -106,12 +106,12 @@ Query OK, 0 rows affected (0.31 sec) In some scenarios, the filtering condition of a query is based on a certain expression. In these scenarios, the query performance is relatively poor because ordinary indexes cannot take effect, the query can only be executed by scanning the entire table. The expression index is a type of special index that can be created on an expression. Once an expression index is created, TiDB can use the index for the expression-based query, which significantly improves the query performance. -For example, if you want to create an index based on `col1+cols2`, execute the following SQL statement: +For example, if you want to create an index based on `lower(col1)`, execute the following SQL statement: {{< copyable "sql" >}} ```sql -CREATE INDEX idx1 ON t1 ((col1 + col2)); +CREATE INDEX idx1 ON t1 (lower(col1)); ``` Or you can execute the following equivalent statement: @@ -119,7 +119,7 @@ Or you can execute the following equivalent statement: {{< copyable "sql" >}} ```sql -ALTER TABLE t1 ADD INDEX idx1((col1 + col2)); +ALTER TABLE t1 ADD INDEX idx1(lower(col1)); ``` You can also specify the expression index when you create the table: @@ -127,7 +127,7 @@ You can also specify the expression index when you create the table: {{< copyable "sql" >}} ```sql -CREATE TABLE t1(col1 char(10), col2 char(10), key index((col1 + col2))); +CREATE TABLE t1(col1 char(10), col2 char(10), key index(lower(col1))); ``` You can drop an expression index in the same way as dropping an ordinary index: @@ -139,6 +139,29 @@ DROP INDEX idx1 ON t1; ``` > **Note:** +> +> An expression index involves multiple expressions. To ensure correctness, only the fully tested functions are allowed to be used to create an expression index currently. That is, only these functions are allowed to be included in expressions in a production environment. You can get these functions by querying +`tidb_allow_function_for_expression_index` variable. In later versions, these functions will be added more. +> +> {{< copyable "sql" >}} +> +> ```sql +> mysql> select @@tidb_allow_function_for_expression_index; +> +--------------------------------------------+ +> | @@tidb_allow_function_for_expression_index | +> +--------------------------------------------+ +> | lower, md5, reverse, upper, vitess_hash | +> +--------------------------------------------+ +> 1 row in set (0.00 sec) +> ``` +> +> For the functions that are not included in the returned result of the above variable, you are not recommended to use those functions in a production environment because they are currently experimental features due to incomplete testing. However, if you still want to use those functions, you can set the configuration as following in the [TiDB configuration file](/tidb-configuration-file.md#allow-expression-index-new-in-v400): +> +> {{< copyable "sql" >}} +> +> ```sql +> allow-expression-index = true +> ``` > > An expression index cannot be created on a primary key. > diff --git a/system-variables.md b/system-variables.md index 475db3907540c..298c501e0403c 100644 --- a/system-variables.md +++ b/system-variables.md @@ -253,6 +253,11 @@ mysql> SELECT * FROM t1; - Default value: "" - This variable is used to specify a list of storage engines that might fall back to TiKV. If the execution of a SQL statement fails due to a failure of the specified storage engine in the list, TiDB retries executing this SQL statement with TiKV. This variable can be set to "" or "tiflash". When this variable is set to "tiflash", if the execution of a SQL statement fails due to a failure of TiFlash, TiDB retries executing this SQL statement with TiKV. +### tidb_allow_function_for_expression_index New in v5.2.0 + +- Scope: NONE +- This variable is used to show the functions that are allowed to be used to create expression indexes. + ### tidb_allow_mpp New in v5.0 - Scope: SESSION | GLOBAL diff --git a/tidb-configuration-file.md b/tidb-configuration-file.md index e9affe81b71b4..9e0ac52d71d67 100644 --- a/tidb-configuration-file.md +++ b/tidb-configuration-file.md @@ -642,3 +642,12 @@ For pessimistic transaction usage, refer to [TiDB Pessimistic Transaction Mode]( + Controls whether the [`INFORMATION_SCHEMA.DEADLOCKS`](/information-schema/information-schema-deadlocks.md) table collects the information of retryable deadlock errors. For the description of retryable deadlock errors, see [Retryable deadlock errors](/information-schema/information-schema-deadlocks.md#retryable-deadlock-errors). + Default value: `false` + +## experimental + +The `experimental` section, introduced in v3.1.0, describes the configurations related to the experimental features of TiDB. + +### `allow-expression-index` New in v4.0.0 + ++ Control whether an expression index can be created. Since TiDB v5.2.0, if the functions in an expression are safe, you can create an expression index directly based on those functions without enabling this configuration. If you want to create an expression index based on other functions, you can enable this configuration, but correctness issues might exist. By querying the `tidb_allow_function_for_expression_index` variable, you get the functions that are safe to be used to create an expression directly. ++ Default value: `false` From d05a68d931aa98a2950017cf1bdc4a99ab7292f1 Mon Sep 17 00:00:00 2001 From: Enwei Date: Thu, 26 Aug 2021 16:24:13 +0200 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: wjHuang --- sql-statements/sql-statement-create-index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-create-index.md b/sql-statements/sql-statement-create-index.md index 8e53c709657f0..46a5a6bf8c1d7 100644 --- a/sql-statements/sql-statement-create-index.md +++ b/sql-statements/sql-statement-create-index.md @@ -140,7 +140,7 @@ DROP INDEX idx1 ON t1; > **Note:** > -> An expression index involves multiple expressions. To ensure correctness, only the fully tested functions are allowed to be used to create an expression index currently. That is, only these functions are allowed to be included in expressions in a production environment. You can get these functions by querying +> Expression index involves various kinds of expressions. To ensure correctness, only the fully tested functions are allowed to be used to create an expression index currently. That is, only these functions are allowed to be included in expressions in a production environment. You can get these functions by querying `tidb_allow_function_for_expression_index` variable. In later versions, these functions will be added more. > > {{< copyable "sql" >}} From 05c147a70a5288a2c605de6a2f98c85727ad402a Mon Sep 17 00:00:00 2001 From: Enwei Date: Fri, 27 Aug 2021 07:22:09 +0200 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- sql-statements/sql-statement-create-index.md | 4 ++-- system-variables.md | 2 +- tidb-configuration-file.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/sql-statements/sql-statement-create-index.md b/sql-statements/sql-statement-create-index.md index 46a5a6bf8c1d7..33ee6c9a92b81 100644 --- a/sql-statements/sql-statement-create-index.md +++ b/sql-statements/sql-statement-create-index.md @@ -140,7 +140,7 @@ DROP INDEX idx1 ON t1; > **Note:** > -> Expression index involves various kinds of expressions. To ensure correctness, only the fully tested functions are allowed to be used to create an expression index currently. That is, only these functions are allowed to be included in expressions in a production environment. You can get these functions by querying +> Expression index involves various kinds of expressions. To ensure correctness, only some fully tested functions are allowed for creating an expression index. This means that only these functions are allowed in expressions in a production environment. You can get these functions by querying `tidb_allow_function_for_expression_index` variable. In future versions, more functions might be added to the list. `tidb_allow_function_for_expression_index` variable. In later versions, these functions will be added more. > > {{< copyable "sql" >}} @@ -155,7 +155,7 @@ DROP INDEX idx1 ON t1; > 1 row in set (0.00 sec) > ``` > -> For the functions that are not included in the returned result of the above variable, you are not recommended to use those functions in a production environment because they are currently experimental features due to incomplete testing. However, if you still want to use those functions, you can set the configuration as following in the [TiDB configuration file](/tidb-configuration-file.md#allow-expression-index-new-in-v400): +> For the functions that are not included in the returned result above, those functions are not fully tested and not recommended for a production environment, which can be seen as experimental. Other expressions such as set operators, `cast`, and `case when` are also seen as experimental and not recommended for production. However, if you still want to use those functions, you can make the following configuration in the [TiDB configuration file](/tidb-configuration-file.md#allow-expression-index-new-in-v400): > > {{< copyable "sql" >}} > diff --git a/system-variables.md b/system-variables.md index 298c501e0403c..dc72322bdc840 100644 --- a/system-variables.md +++ b/system-variables.md @@ -256,7 +256,7 @@ mysql> SELECT * FROM t1; ### tidb_allow_function_for_expression_index New in v5.2.0 - Scope: NONE -- This variable is used to show the functions that are allowed to be used to create expression indexes. +- This variable is used to show the functions that are allowed to be used for creating expression indexes. ### tidb_allow_mpp New in v5.0 diff --git a/tidb-configuration-file.md b/tidb-configuration-file.md index 9e0ac52d71d67..a790e94a644e0 100644 --- a/tidb-configuration-file.md +++ b/tidb-configuration-file.md @@ -649,5 +649,5 @@ The `experimental` section, introduced in v3.1.0, describes the configurations r ### `allow-expression-index` New in v4.0.0 -+ Control whether an expression index can be created. Since TiDB v5.2.0, if the functions in an expression are safe, you can create an expression index directly based on those functions without enabling this configuration. If you want to create an expression index based on other functions, you can enable this configuration, but correctness issues might exist. By querying the `tidb_allow_function_for_expression_index` variable, you get the functions that are safe to be used to create an expression directly. ++ Controls whether an expression index can be created. Since TiDB v5.2.0, if the function in an expression is safe, you can create an expression index directly based on this function without enabling this configuration. If you want to create an expression index based on other functions, you can enable this configuration, but correctness issues might exist. By querying the `tidb_allow_function_for_expression_index` variable, you can get the functions that are safe to be directly used for creating an expression. + Default value: `false` From ab2033bf68537abf790eb4781fc57cf140da1c1c Mon Sep 17 00:00:00 2001 From: Enwei Date: Fri, 27 Aug 2021 07:24:31 +0200 Subject: [PATCH 4/5] Apply suggestions from code review --- sql-statements/sql-statement-create-index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/sql-statements/sql-statement-create-index.md b/sql-statements/sql-statement-create-index.md index 33ee6c9a92b81..61e19904b370d 100644 --- a/sql-statements/sql-statement-create-index.md +++ b/sql-statements/sql-statement-create-index.md @@ -141,7 +141,6 @@ DROP INDEX idx1 ON t1; > **Note:** > > Expression index involves various kinds of expressions. To ensure correctness, only some fully tested functions are allowed for creating an expression index. This means that only these functions are allowed in expressions in a production environment. You can get these functions by querying `tidb_allow_function_for_expression_index` variable. In future versions, more functions might be added to the list. -`tidb_allow_function_for_expression_index` variable. In later versions, these functions will be added more. > > {{< copyable "sql" >}} > From 7775ce4fbb74d15b9a0969b364cf3deaed8727d7 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Fri, 27 Aug 2021 13:50:39 +0800 Subject: [PATCH 5/5] Update sql-statements/sql-statement-create-index.md Co-authored-by: wjHuang --- sql-statements/sql-statement-create-index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-create-index.md b/sql-statements/sql-statement-create-index.md index 61e19904b370d..f59ac132dfdad 100644 --- a/sql-statements/sql-statement-create-index.md +++ b/sql-statements/sql-statement-create-index.md @@ -154,7 +154,7 @@ DROP INDEX idx1 ON t1; > 1 row in set (0.00 sec) > ``` > -> For the functions that are not included in the returned result above, those functions are not fully tested and not recommended for a production environment, which can be seen as experimental. Other expressions such as set operators, `cast`, and `case when` are also seen as experimental and not recommended for production. However, if you still want to use those functions, you can make the following configuration in the [TiDB configuration file](/tidb-configuration-file.md#allow-expression-index-new-in-v400): +> For the functions that are not included in the returned result above, those functions are not fully tested and not recommended for a production environment, which can be seen as experimental. Other expressions such as operators, `cast`, and `case when` are also seen as experimental and not recommended for production. However, if you still want to use those expressions, you can make the following configuration in the [TiDB configuration file](/tidb-configuration-file.md#allow-expression-index-new-in-v400): > > {{< copyable "sql" >}} >