Skip to content
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

Jump to bottom

sql: update doc for json format explain #11471

Merged
merged 6 commits into from
Dec 6, 2022
Merged

sql: update doc for json format explain #11471

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f48b210
update doc for json format explain
ran-huang Nov 30, 2022
203f978
align comments
ran-huang Dec 1, 2022
6ca2029
Apply suggestions from code review
ran-huang Dec 5, 2022
98fb183
sync changes
ran-huang Dec 5, 2022
850a9c7
Update sql-statements/sql-statement-explain.md
ran-huang Dec 6, 2022
7847f57
Apply suggestions from code review
ran-huang Dec 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
65 changes: 63 additions & 2 deletions sql-statements/sql-statement-explain.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,14 +187,19 @@ EXPLAIN DELETE FROM t1 WHERE c1=3;
4 rows in set (0.01 sec)
```

To specify the content and format of the output, you can use the `FORMAT = xxx` syntax in the `EXPLAIN` statement.
To specify the format of the `EXPLAIN` output, you can use the `FORMAT = xxx` syntax. Currently, TiDB supports the following formats:

| FORMAT | Description |
| ------ | ------ |
| Empty | Same as `row` |
| Not specified | If the format is not specified, `EXPLAIN` uses the default format `row`. |
| `row` | The `EXPLAIN` statement outputs results in a tabular format. See [Understand the Query Execution Plan](/explain-overview.md) for more information. |
| `brief` | The operator IDs in the output of the `EXPLAIN` statement are simplified, compared with those when `FORMAT` is left unspecified. |
| `dot` | The `EXPLAIN` statement outputs DOT execution plans, which can be used to generate PNG files through a `dot` program (in the `graphviz` package). |
| `tidb_json` | The `EXPLAIN` statement outputs execution plans in JSON and stores the operator information in a JSON array. |

<SimpleTab>

<div label="brief">

The following is an example when `FORMAT` is `"brief"` in `EXPLAIN`:

Expand All @@ -216,6 +221,10 @@ EXPLAIN FORMAT = "brief" DELETE FROM t1 WHERE c1 = 3;
4 rows in set (0.001 sec)
```

</div>

<div label="DotGraph">

In addition to the MySQL standard result format, TiDB also supports DotGraph and you need to specify `FORMAT = "dot"` as in the following example:

{{< copyable "sql" >}}
Expand Down Expand Up @@ -272,10 +281,62 @@ If your computer has no `dot` program, copy the result to [this website](http://

![Explain Dot](/media/explain_dot.png)

</div>

<div label="JSON">

To get the output in JSON, specify `FORMAT = "tidb_json"` in the `EXPLAIN` statement. The following is an example:

```sql
CREATE TABLE t(id int primary key, a int, b int, key(a));
EXPLAIN FORMAT = "tidb_json" SELECT id FROM t WHERE a = 1;
```

```
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| TiDB_JSON |
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| [
{
"id": "Projection_4",
"estRows": "10.00",
"taskType": "root",
"operatorInfo": "test.t.id",
"subOperators": [
{
"id": "IndexReader_6",
"estRows": "10.00",
"taskType": "root",
"operatorInfo": "index:IndexRangeScan_5",
"subOperators": [
{
"id": "IndexRangeScan_5",
"estRows": "10.00",
"taskType": "cop[tikv]",
"accessObject": "table:t, index:a(a)",
"operatorInfo": "range:[1,1], keep order:false, stats:pseudo"
}
]
}
]
}
]
|
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1 row in set (0.01 sec)
```

In the output, `id`, `estRows`, `taskType`, `accessObject`, and `operatorInfo` have the same meaning as the columns in the default format. `subOperators` is an array that stores the sub-nodes. The fields and meanings of the sub-nodes are the same as the parent nodes. If a field is missing, it means that the field is empty.
ran-huang marked this conversation as resolved.
Show resolved Hide resolved

</div>

</SimpleTab>

## MySQL compatibility

* Both the format of `EXPLAIN` and the potential execution plans in TiDB differ substaintially from MySQL.
* TiDB does not support the `FORMAT=JSON` or `FORMAT=TREE` options.
* `FORMAT=tidb_json` in TiDB is the default `EXPLAIN` output encoded in JSON. The format and fields are different from the `FORMAT=JSON` output in MySQL.
ran-huang marked this conversation as resolved.
Show resolved Hide resolved

### `EXPLAIN FOR CONNECTION`

Expand Down