From 31fc005064a8d2993e2971e4c8ed6583c19f5911 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 03317dea5abd7..5b3a39643e8c5 100644 --- a/sql-statements/sql-statement-create-index.md +++ b/sql-statements/sql-statement-create-index.md @@ -105,12 +105,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: @@ -118,7 +118,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: @@ -126,7 +126,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: @@ -138,6 +138,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 e6e3c6d1057c3..779bd80f76b8f 100644 --- a/system-variables.md +++ b/system-variables.md @@ -252,6 +252,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 cc9b26d559467..4cfac8be9bb9e 100644 --- a/tidb-configuration-file.md +++ b/tidb-configuration-file.md @@ -641,3 +641,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 f36d89bbb9daac6ac4d7e89e0293b308bd14cedd 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 5b3a39643e8c5..bdf77a5c81ca7 100644 --- a/sql-statements/sql-statement-create-index.md +++ b/sql-statements/sql-statement-create-index.md @@ -139,7 +139,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 d3c4a9f1bf5d03aa57d40ca10d4a06a9a8416110 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 bdf77a5c81ca7..c8f81c2c0047b 100644 --- a/sql-statements/sql-statement-create-index.md +++ b/sql-statements/sql-statement-create-index.md @@ -139,7 +139,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" >}} @@ -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 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 779bd80f76b8f..714601972c126 100644 --- a/system-variables.md +++ b/system-variables.md @@ -255,7 +255,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 4cfac8be9bb9e..40867686bccb0 100644 --- a/tidb-configuration-file.md +++ b/tidb-configuration-file.md @@ -648,5 +648,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 59b283d1cacc0f21402acd8e8ef235795a02e70a 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 c8f81c2c0047b..2511a8294a5f4 100644 --- a/sql-statements/sql-statement-create-index.md +++ b/sql-statements/sql-statement-create-index.md @@ -140,7 +140,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 dc999eaa0e6d193670baf13f568095608355756b 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 2511a8294a5f4..5b99bccd9f252 100644 --- a/sql-statements/sql-statement-create-index.md +++ b/sql-statements/sql-statement-create-index.md @@ -153,7 +153,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" >}} >