Skip to content

planner: Plan Replayer supports dumping multiple statement at once #22429

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
qw4990 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

planner: Plan Replayer supports dumping multiple statement at once #22429

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions sql-plan-replayer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,10 @@ You can use `PLAN REPLAYER` to save the on-site information of a TiDB cluster. T

```sql
PLAN REPLAYER DUMP [WITH STATS AS OF TIMESTAMP expression] EXPLAIN [ANALYZE] sql-statement;
PLAN REPLAYER DUMP EXPLAIN [ANALYZE] ( 'sql1', 'sql2', ... );
```

Based on `sql-statement`, TiDB sorts out and exports the following on-site information:
Based on the SQL statement or statements, TiDB sorts out and exports the following on-site information:

- TiDB version
- TiDB configuration
Expand All @@ -31,6 +32,11 @@ Based on `sql-statement`, TiDB sorts out and exports the following on-site infor
- The result of `EXPLAIN [ANALYZE] sql-statement`
- Some internal procedures of query optimization

Depending on whether you dump a single SQL statement or multiple SQL statements, the structure of the exported ZIP file is as follows:

- For a single SQL statement, the ZIP file includes `sql/sql0.sql` and `explain.txt`.
- For multiple SQL statements, the ZIP file includes `sql/sql0.sql`, `sql/sql1.sql`, ... and the corresponding `explain/explain0.txt`, `explain/explain1.txt`, ..., together with schema and statistics files for the referenced tables.
Comment on lines +35 to +38
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low

To improve clarity, this section can be rephrased to be more direct and avoid using '...'.

Suggested change
Depending on whether you dump a single SQL statement or multiple SQL statements, the structure of the exported ZIP file is as follows:
- For a single SQL statement, the ZIP file includes `sql/sql0.sql` and `explain.txt`.
- For multiple SQL statements, the ZIP file includes `sql/sql0.sql`, `sql/sql1.sql`, ... and the corresponding `explain/explain0.txt`, `explain/explain1.txt`, ..., together with schema and statistics files for the referenced tables.
The structure of the exported ZIP file depends on whether you dump a single SQL statement or multiple SQL statements:
- For a single SQL statement, the ZIP file includes `sql/sql0.sql` and `explain.txt`.
- For multiple SQL statements, the ZIP file includes SQL files such as `sql/sql0.sql` and `sql/sql1.sql`, their corresponding explain files such as `explain/explain0.txt` and `explain/explain1.txt`, and the schema and statistics files for the referenced tables.
References
  1. The style guide emphasizes clarity, simplicity, and readability (line 14). The suggested change improves readability by making the sentence structure simpler and avoiding the informal '...'. (link)


If historical statistics are [enabled](/system-variables.md#tidb_enable_historical_stats), you can specify a time in the `PLAN REPLAYER` statement to get the historical statistics for the corresponding time. You can directly specify a time and date or specify a timestamp. TiDB looks for the historical statistics before the specified time and exports the latest one among them.

If there are no historical statistics before the specified time, TiDB exports the latest statistics, which is consistent with the behavior when no time is specified. In addition, TiDB prints the error messages in the `errors.txt` file within the exported `ZIP` file.
Expand Down Expand Up @@ -88,7 +94,18 @@ SELECT @@tidb_last_plan_replayer_token;
1 row in set (0.00 sec)
```

When there are multiple SQL statements, you can obtain the result of the `PLAN REPLAYER DUMP` execution using a file. The results of multiple SQL statements are separated by `;` in this file.
To dump multiple SQL statements in a single command, you can use the multi-statement syntax:

{{< copyable "sql" >}}

```sql
PLAN REPLAYER DUMP EXPLAIN (
'SELECT * FROM t WHERE a = 1',
'SELECT * FROM t WHERE b > 1'
);
```

Alternatively, when there are multiple SQL statements, you can obtain the result of the `PLAN REPLAYER DUMP` execution using a file. The results of multiple SQL statements are separated by `;` in this file.
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low

This sentence can be simplified for better readability and to be more direct for the user, in line with the style guide's preference for using the second person ('you').

Suggested change
Alternatively, when there are multiple SQL statements, you can obtain the result of the `PLAN REPLAYER DUMP` execution using a file. The results of multiple SQL statements are separated by `;` in this file.
Alternatively, you can dump multiple SQL statements from a file. In this file, separate SQL statements with a semicolon (`;`).
References
  1. The style guide recommends writing in the second person ('you') (line 22) and preferring clarity and simplicity (line 14). The suggested change makes the instruction more direct and easier for the user to follow. (link)


```sql
plan replayer dump explain 'sqls.txt';
Expand Down