Skip to content

Commit bef486f

Browse files
update doc for SPM (#6146)
1 parent 4790fa8 commit bef486f

File tree

1 file changed

+34
-3
lines changed

1 file changed

+34
-3
lines changed

sql-plan-management.md

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,10 @@ explain select * from t1,t2 where t1.id = t2.id;
162162

163163
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.
164164

165+
> **Note:**
166+
>
167+
> 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).
168+
165169
### View binding
166170

167171
{{< copyable "sql" >}}
@@ -170,7 +174,7 @@ In the example above, the dropped binding in the SESSION scope shields the corre
170174
SHOW [GLOBAL | SESSION] BINDINGS [ShowLikeOrWhere]
171175
```
172176

173-
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:
177+
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:
174178

175179
| Column Name | Note |
176180
| :-------- | :------------- |
@@ -184,6 +188,32 @@ This statement outputs the execution plan bindings at the GLOBAL or SESSION leve
184188
| collation | Ordering rule |
185189
| 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) |
186190

191+
### Troubleshoot binding
192+
193+
{{< copyable "sql" >}}
194+
195+
```sql
196+
SELECT [SESSION] @@last_plan_from_binding;
197+
```
198+
199+
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.
200+
201+
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.
202+
203+
```sql
204+
-- Create a global binding.
205+
206+
create global binding for
207+
select * from t
208+
using
209+
select * from t;
210+
211+
-- Use the `explain format = 'verbose'` statement to check the SQL execution plan. Check the warning message to view the binding used in the query.
212+
213+
explain format = 'verbose' select * from t;
214+
show warnings;
215+
```
216+
187217
## Baseline capturing
188218

189219
To enable baseline capturing, set `tidb_capture_plan_baselines` to `on`. The default value is `off`.
@@ -226,9 +256,10 @@ set global tidb_evolve_plan_baselines = on;
226256

227257
The default value of `tidb_evolve_plan_baselines` is `off`.
228258

229-
> **Note:**
259+
> **Warning:**
230260
>
231-
> The feature baseline evolution is not generally available for now. It is **NOT RECOMMENDED** to use it in the production environment.
261+
> + Baseline evolution is an experimental feature. Unknown risks might exist. It is **NOT** recommended that you use it in the production environment.
262+
> + 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.
232263
233264
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.
234265

0 commit comments

Comments
 (0)