Skip to content

Commit

Permalink
sql: update doc for json format explain (#11471)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ran-huang
ran-huang committed Dec 6, 2022
1 parent 455b112 commit 603bcea
Showing 1 changed file with 63 additions and 2 deletions.
65 changes: 63 additions & 2 deletions sql-statements/sql-statement-explain.md
View file
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 node. If a field is missing, it means that the field is empty.

</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 JSON format output of the default `EXPLAIN` result. The format and fields are different from the `FORMAT=JSON` output in MySQL.

### `EXPLAIN FOR CONNECTION`

Expand Down

0 comments on commit 603bcea

Please sign in to comment.