From 15e0aae5e13353356ff393e0f079bc033bdc47ee Mon Sep 17 00:00:00 2001 From: Xiaozhen Liu Date: Wed, 11 Aug 2021 16:14:21 +0800 Subject: [PATCH 1/9] update doc for SPM --- sql-plan-management.md | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/sql-plan-management.md b/sql-plan-management.md index b2cf69acd8969..5716958afefe1 100644 --- a/sql-plan-management.md +++ b/sql-plan-management.md @@ -162,6 +162,10 @@ explain select * from t1,t2 where t1.id = t2.id; In the example above, the dropped binding in the SESSION scope shields the corresponding binding in the GLOBAL scope. The optimizer does not add the `sm_join(t1, t2)` hint to the statement. The top node of the execution plan in the `explain` result is not fixed to MergeJoin by this hint. Instead, the top node is independently selected by the optimizer according to the cost estimation. +> **Note:** +> +> Executing `DROP GLOBAL BINDING` drops the binding in the current tidb-server instance cache and changes the status of the corresponding row in the system table to 'deleted'. This statement will not directly delete the records in the system table, because other tidb-server instances need to read the 'deleted' status to drop the corresponding binding in their cache. For the records in these system tables with the status of 'deleted', at every 100 `bind-info-lease` (the default value is `3s`, `300s` in total) interval, the background thread triggers an operation of reclaiming and clearing to 10 bindings of `update_time` before `bind-info-lease` (to ensure that all tidb-server instances have read the 'deleted' status and updated the cache). + ### View binding {{< copyable "sql" >}} @@ -170,7 +174,7 @@ In the example above, the dropped binding in the SESSION scope shields the corre SHOW [GLOBAL | SESSION] BINDINGS [ShowLikeOrWhere] ``` -This statement outputs the execution plan bindings at the GLOBAL or SESSION level. The default scope is SESSION. Currently `SHOW BINDINGS` outputs eight columns, as shown below: +This statement outputs the execution plan bindings at the GLOBAL or SESSION level according to the order of binding update time from late to early. The default scope is SESSION. Currently `SHOW BINDINGS` outputs eight columns, as shown below: | Column Name | Note | | :-------- | :------------- | @@ -184,6 +188,29 @@ This statement outputs the execution plan bindings at the GLOBAL or SESSION leve | collation | Ordering rule | | source | The way in which a binding is created, including `manual` (created by the `create [global] binding` SQL statement), `capture` (captured automatically by TiDB), and `evolve` (evolved automatically by TiDB) | +### Troubleshoot binding + +{{< copyable "sql" >}} + +```sql +SELECT [SESSION] @@last_plan_from_binding; +``` + +This statement uses the system variable [`last_plan_from_binding`](/system-variables.md#last_plan_from_binding-new-in-v40) to show whether the execution plan used by the last executed statement is from the execution plan of binding. + +In addition, when you use the `explain format = 'verbose'` statement to view the query plan of an SQL statement, if the SQL statement uses binding, the `explain` statement will return a warning. Under this condition, you can check the warning message to learn which binding is used in the SQL statement. + +```sql +-- Create a global binding. +create global binding for + select * from t +using + select * from t; +-- Use explain format = 'verbose' statement to check the execution plan of SQL. Check the warning message to view the binding for query. +explain format = 'verbose' select * from t; +show warnings; +``` + ## Baseline capturing To enable baseline capturing, set `tidb_capture_plan_baselines` to `on`. The default value is `off`. @@ -226,9 +253,10 @@ set global tidb_evolve_plan_baselines = on; The default value of `tidb_evolve_plan_baselines` is `off`. -> **Note:** +> **Warning:** > -> The feature baseline evolution is not generally available for now. It is **NOT RECOMMENDED** to use it in the production environment. +> The feature baseline evolution is an experimental feature. Unknown risks exist. It is **NOT** recommended that you use it in the production environment. +> This variable switch is forced off until it automatically evolves to be generally available. If you try to enable the feature, an error will be returned. If you have already used this feature in a production environment, disable it as soon as possible. If you find that the binding status is not as expected, contact PingCAP's technical supporters for help. After the automatic binding evolution feature is enabled, if the optimal execution plan selected by the optimizer is not among the binding execution plans, the optimizer marks the plan as an execution plan that waits for verification. At every `bind-info-lease` (the default value is `3s`) interval, an execution plan to be verified is selected and compared with the binding execution plan that has the least cost in terms of the actual execution time. If the plan to be verified has shorter execution time (the current criterion for the comparison is that the execution time of the plan to be verified is no longer than 2/3 that of the binding execution plan), this plan is marked as a usable binding. The following example describes the process above. From 6019f1dd9d2e5d273f5cb7d50928b92130361c78 Mon Sep 17 00:00:00 2001 From: Liuxiaozhen12 <82579298+Liuxiaozhen12@users.noreply.github.com> Date: Tue, 17 Aug 2021 18:23:40 +0800 Subject: [PATCH 2/9] Apply suggestions from code review Co-authored-by: Chengpeng Yan <41809508+Reminiscent@users.noreply.github.com> --- sql-plan-management.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sql-plan-management.md b/sql-plan-management.md index 5716958afefe1..77c6d75f6ecc6 100644 --- a/sql-plan-management.md +++ b/sql-plan-management.md @@ -164,7 +164,7 @@ In the example above, the dropped binding in the SESSION scope shields the corre > **Note:** > -> Executing `DROP GLOBAL BINDING` drops the binding in the current tidb-server instance cache and changes the status of the corresponding row in the system table to 'deleted'. This statement will not directly delete the records in the system table, because other tidb-server instances need to read the 'deleted' status to drop the corresponding binding in their cache. For the records in these system tables with the status of 'deleted', at every 100 `bind-info-lease` (the default value is `3s`, `300s` in total) interval, the background thread triggers an operation of reclaiming and clearing to 10 bindings of `update_time` before `bind-info-lease` (to ensure that all tidb-server instances have read the 'deleted' status and updated the cache). +> Executing `DROP GLOBAL BINDING` drops the binding in the current tidb-server instance cache and changes the status of the corresponding row in the system table to 'deleted'. This statement will not directly delete the records in the system table, because other tidb-server instances need to read the 'deleted' status to drop the corresponding binding in their cache. For the records in these system tables with the status of 'deleted', at every 100 `bind-info-lease` (the default value is `3s`, `300s` in total) interval, the background thread triggers an operation of reclaiming and clearing to bindings of `update_time` before 10 `bind-info-lease` (to ensure that all tidb-server instances have read the 'deleted' status and updated the cache). ### View binding @@ -196,7 +196,7 @@ This statement outputs the execution plan bindings at the GLOBAL or SESSION leve SELECT [SESSION] @@last_plan_from_binding; ``` -This statement uses the system variable [`last_plan_from_binding`](/system-variables.md#last_plan_from_binding-new-in-v40) to show whether the execution plan used by the last executed statement is from the execution plan of binding. +This statement uses the system variable [`last_plan_from_binding`](/system-variables.md#last_plan_from_binding-new-in-v40) to show whether the execution plan used by the last executed statement is from the binding. In addition, when you use the `explain format = 'verbose'` statement to view the query plan of an SQL statement, if the SQL statement uses binding, the `explain` statement will return a warning. Under this condition, you can check the warning message to learn which binding is used in the SQL statement. @@ -256,7 +256,7 @@ The default value of `tidb_evolve_plan_baselines` is `off`. > **Warning:** > > The feature baseline evolution is an experimental feature. Unknown risks exist. It is **NOT** recommended that you use it in the production environment. -> This variable switch is forced off until it automatically evolves to be generally available. If you try to enable the feature, an error will be returned. If you have already used this feature in a production environment, disable it as soon as possible. If you find that the binding status is not as expected, contact PingCAP's technical supporters for help. +> This variable switch is forced off until the feature baseline evolution to be generally available. If you try to enable the feature, an error will be returned. If you have already used this feature in a production environment, disable it as soon as possible. If you find that the binding status is not as expected, contact PingCAP's technical supporters for help. After the automatic binding evolution feature is enabled, if the optimal execution plan selected by the optimizer is not among the binding execution plans, the optimizer marks the plan as an execution plan that waits for verification. At every `bind-info-lease` (the default value is `3s`) interval, an execution plan to be verified is selected and compared with the binding execution plan that has the least cost in terms of the actual execution time. If the plan to be verified has shorter execution time (the current criterion for the comparison is that the execution time of the plan to be verified is no longer than 2/3 that of the binding execution plan), this plan is marked as a usable binding. The following example describes the process above. From 016dc99782ebf0008b633e63eeba80181a8300f3 Mon Sep 17 00:00:00 2001 From: Xiaozhen Liu Date: Wed, 18 Aug 2021 11:33:48 +0800 Subject: [PATCH 3/9] Update sql-plan-management.md --- sql-plan-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-plan-management.md b/sql-plan-management.md index 77c6d75f6ecc6..9a00c4fcbe87c 100644 --- a/sql-plan-management.md +++ b/sql-plan-management.md @@ -174,7 +174,7 @@ In the example above, the dropped binding in the SESSION scope shields the corre SHOW [GLOBAL | SESSION] BINDINGS [ShowLikeOrWhere] ``` -This statement outputs the execution plan bindings at the GLOBAL or SESSION level according to the order of binding update time from late to early. The default scope is SESSION. Currently `SHOW BINDINGS` outputs eight columns, as shown below: +This statement outputs the execution plan bindings at the GLOBAL or SESSION level according to the order of binding update time from the latest to earliest. The default scope is SESSION. Currently `SHOW BINDINGS` outputs eight columns, as shown below: | Column Name | Note | | :-------- | :------------- | From 57cf43dff1ea7488627a50ccec4abd28918f6b36 Mon Sep 17 00:00:00 2001 From: Liuxiaozhen12 <82579298+Liuxiaozhen12@users.noreply.github.com> Date: Thu, 19 Aug 2021 16:43:39 +0800 Subject: [PATCH 4/9] Apply suggestions from code review Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- sql-plan-management.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sql-plan-management.md b/sql-plan-management.md index 9a00c4fcbe87c..3c9268107d05a 100644 --- a/sql-plan-management.md +++ b/sql-plan-management.md @@ -164,7 +164,7 @@ In the example above, the dropped binding in the SESSION scope shields the corre > **Note:** > -> Executing `DROP GLOBAL BINDING` drops the binding in the current tidb-server instance cache and changes the status of the corresponding row in the system table to 'deleted'. This statement will not directly delete the records in the system table, because other tidb-server instances need to read the 'deleted' status to drop the corresponding binding in their cache. For the records in these system tables with the status of 'deleted', at every 100 `bind-info-lease` (the default value is `3s`, `300s` in total) interval, the background thread triggers an operation of reclaiming and clearing to bindings of `update_time` before 10 `bind-info-lease` (to ensure that all tidb-server instances have read the 'deleted' status and updated the cache). +> Executing `DROP GLOBAL BINDING` drops the binding in the current tidb-server instance cache and changes the status of the corresponding row in the system table to 'deleted'. This statement does not directly delete the records in the system table, because other tidb-server instances need to read the 'deleted' status to drop the corresponding binding in their cache. For the records in these system tables with the status of 'deleted', at every 100 `bind-info-lease` (the default value is `3s`, and `300s` in total) interval, the background thread triggers an operation of reclaiming and clearing on the bindings of `update_time` before 10 `bind-info-lease` (to ensure that all tidb-server instances have read the 'deleted' status and updated the cache). ### View binding @@ -198,7 +198,7 @@ SELECT [SESSION] @@last_plan_from_binding; This statement uses the system variable [`last_plan_from_binding`](/system-variables.md#last_plan_from_binding-new-in-v40) to show whether the execution plan used by the last executed statement is from the binding. -In addition, when you use the `explain format = 'verbose'` statement to view the query plan of an SQL statement, if the SQL statement uses binding, the `explain` statement will return a warning. Under this condition, you can check the warning message to learn which binding is used in the SQL statement. +In addition, when you use the `explain format = 'verbose'` statement to view the query plan of a SQL statement, if the SQL statement uses binding, the `explain` statement will return a warning. In this situation, you can check the warning message to learn which binding is used in the SQL statement. ```sql -- Create a global binding. @@ -255,8 +255,8 @@ The default value of `tidb_evolve_plan_baselines` is `off`. > **Warning:** > -> The feature baseline evolution is an experimental feature. Unknown risks exist. It is **NOT** recommended that you use it in the production environment. -> This variable switch is forced off until the feature baseline evolution to be generally available. If you try to enable the feature, an error will be returned. If you have already used this feature in a production environment, disable it as soon as possible. If you find that the binding status is not as expected, contact PingCAP's technical supporters for help. +> + Baseline evolution is an experimental feature. Unknown risks exist. It is **NOT** recommended that you use it in the production environment. +> This variable is forcibly set to `off` until the baseline evolution feature becomes generally available (GA). If you try to enable this feature, an error is returned. If you have already used this feature in a production environment, disable it as soon as possible. If you find that the binding status is not as expected, contact PingCAP's technical support for help. After the automatic binding evolution feature is enabled, if the optimal execution plan selected by the optimizer is not among the binding execution plans, the optimizer marks the plan as an execution plan that waits for verification. At every `bind-info-lease` (the default value is `3s`) interval, an execution plan to be verified is selected and compared with the binding execution plan that has the least cost in terms of the actual execution time. If the plan to be verified has shorter execution time (the current criterion for the comparison is that the execution time of the plan to be verified is no longer than 2/3 that of the binding execution plan), this plan is marked as a usable binding. The following example describes the process above. From 5973fd021ea3bb0c7f8ffcd51748f5fc54c8ab7f Mon Sep 17 00:00:00 2001 From: Liuxiaozhen12 <82579298+Liuxiaozhen12@users.noreply.github.com> Date: Thu, 19 Aug 2021 16:45:20 +0800 Subject: [PATCH 5/9] Apply suggestions from code review Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- sql-plan-management.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/sql-plan-management.md b/sql-plan-management.md index 3c9268107d05a..7b8dafbcc7f8b 100644 --- a/sql-plan-management.md +++ b/sql-plan-management.md @@ -202,11 +202,14 @@ In addition, when you use the `explain format = 'verbose'` statement to view the ```sql -- Create a global binding. + create global binding for select * from t using select * from t; --- Use explain format = 'verbose' statement to check the execution plan of SQL. Check the warning message to view the binding for query. + +-- Use the `explain format = 'verbose'` statement to check the SQL execution plan. Check the warning message to view the binding used in the query. + explain format = 'verbose' select * from t; show warnings; ``` From 294fc22ef47c3fc210f994ae6a28409b8f74c7a6 Mon Sep 17 00:00:00 2001 From: Liuxiaozhen12 <82579298+Liuxiaozhen12@users.noreply.github.com> Date: Thu, 19 Aug 2021 16:46:37 +0800 Subject: [PATCH 6/9] Update sql-plan-management.md Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- sql-plan-management.md | 1 + 1 file changed, 1 insertion(+) diff --git a/sql-plan-management.md b/sql-plan-management.md index 7b8dafbcc7f8b..81184ff984915 100644 --- a/sql-plan-management.md +++ b/sql-plan-management.md @@ -203,6 +203,7 @@ In addition, when you use the `explain format = 'verbose'` statement to view the ```sql -- Create a global binding. + create global binding for select * from t using From a6211f36d5c4eaa7a391cc3a8e9585fc198df580 Mon Sep 17 00:00:00 2001 From: Liuxiaozhen12 <82579298+Liuxiaozhen12@users.noreply.github.com> Date: Thu, 19 Aug 2021 16:56:33 +0800 Subject: [PATCH 7/9] Update sql-plan-management.md --- sql-plan-management.md | 1 - 1 file changed, 1 deletion(-) diff --git a/sql-plan-management.md b/sql-plan-management.md index 81184ff984915..7b8dafbcc7f8b 100644 --- a/sql-plan-management.md +++ b/sql-plan-management.md @@ -203,7 +203,6 @@ In addition, when you use the `explain format = 'verbose'` statement to view the ```sql -- Create a global binding. - create global binding for select * from t using From cd81a266748cd3dc0d2f501f49cd942e61190b8c Mon Sep 17 00:00:00 2001 From: Liuxiaozhen12 <82579298+Liuxiaozhen12@users.noreply.github.com> Date: Thu, 19 Aug 2021 17:04:06 +0800 Subject: [PATCH 8/9] Update sql-plan-management.md Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- sql-plan-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-plan-management.md b/sql-plan-management.md index 7b8dafbcc7f8b..b3d76f876c09f 100644 --- a/sql-plan-management.md +++ b/sql-plan-management.md @@ -258,7 +258,7 @@ The default value of `tidb_evolve_plan_baselines` is `off`. > **Warning:** > -> + Baseline evolution is an experimental feature. Unknown risks exist. It is **NOT** recommended that you use it in the production environment. +> + Baseline evolution is an experimental feature. Unknown risks might exist. It is **NOT** recommended that you use it in the production environment. > This variable is forcibly set to `off` until the baseline evolution feature becomes generally available (GA). If you try to enable this feature, an error is returned. If you have already used this feature in a production environment, disable it as soon as possible. If you find that the binding status is not as expected, contact PingCAP's technical support for help. After the automatic binding evolution feature is enabled, if the optimal execution plan selected by the optimizer is not among the binding execution plans, the optimizer marks the plan as an execution plan that waits for verification. At every `bind-info-lease` (the default value is `3s`) interval, an execution plan to be verified is selected and compared with the binding execution plan that has the least cost in terms of the actual execution time. If the plan to be verified has shorter execution time (the current criterion for the comparison is that the execution time of the plan to be verified is no longer than 2/3 that of the binding execution plan), this plan is marked as a usable binding. The following example describes the process above. From 55298b1cd51b3da1002c41177673bd2ffaacea53 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Fri, 20 Aug 2021 15:27:52 +0800 Subject: [PATCH 9/9] Update sql-plan-management.md --- sql-plan-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-plan-management.md b/sql-plan-management.md index b3d76f876c09f..8aff1b1841cfa 100644 --- a/sql-plan-management.md +++ b/sql-plan-management.md @@ -259,7 +259,7 @@ The default value of `tidb_evolve_plan_baselines` is `off`. > **Warning:** > > + Baseline evolution is an experimental feature. Unknown risks might exist. It is **NOT** recommended that you use it in the production environment. -> This variable is forcibly set to `off` until the baseline evolution feature becomes generally available (GA). If you try to enable this feature, an error is returned. If you have already used this feature in a production environment, disable it as soon as possible. If you find that the binding status is not as expected, contact PingCAP's technical support for help. +> + This variable is forcibly set to `off` until the baseline evolution feature becomes generally available (GA). If you try to enable this feature, an error is returned. If you have already used this feature in a production environment, disable it as soon as possible. If you find that the binding status is not as expected, contact PingCAP's technical support for help. After the automatic binding evolution feature is enabled, if the optimal execution plan selected by the optimizer is not among the binding execution plans, the optimizer marks the plan as an execution plan that waits for verification. At every `bind-info-lease` (the default value is `3s`) interval, an execution plan to be verified is selected and compared with the binding execution plan that has the least cost in terms of the actual execution time. If the plan to be verified has shorter execution time (the current criterion for the comparison is that the execution time of the plan to be verified is no longer than 2/3 that of the binding execution plan), this plan is marked as a usable binding. The following example describes the process above.