EXPLAIN and PROFILE¶
EXPLAIN helps output the execution plan of an nGQL statement without executing the statement.
PROFILE executes the statement, then outputs the execution plan as well as the execution profile. You can optimize the queries for better performance according to the execution plan and profile.
Execution Plan¶
The execution plan is determined by the execution planner in the NebulaGraph query engine.
The execution planner processes the parsed nGQL statements into actions. An action is the smallest unit that can be executed. A typical action fetches all neighbors of a given vertex, gets the properties of an edge, and filters vertices or edges based on the given conditions. Each action is assigned to an operator that performs the action.
For example, a SHOW TAGS statement is processed into two actions and assigned to a Start operator and a ShowTags operator, while a more complex GO statement may be processed into more than 10 actions and assigned to 10 operators.
Syntax¶
EXPLAINEXPLAIN [format= {"row" | "dot" | "tck"}] <your_nGQL_statement>;
PROFILEPROFILE [format= {"row" | "dot" | "tck"}] <your_nGQL_statement>;
Output formats¶
The output of an EXPLAIN or a PROFILE statement has three formats, the default row format, the dot format, and the tck format. You can use the format option to modify the output format. Omitting the format option indicates using the default row format.
The row format¶
The row format outputs the return message in a table as follows.
EXPLAINnebula> EXPLAIN format="row" SHOW TAGS; Execution succeeded (time spent 327/892 us) Execution Plan -----+----------+--------------+----------------+---------------------------------------------------------------------- | id | name | dependencies | profiling data | operator info | -----+----------+--------------+----------------+---------------------------------------------------------------------- | 1 | ShowTags | 0 | | outputVar: [{"colNames":[],"name":"__ShowTags_1","type":"DATASET"}] | | | | | | inputVar: | -----+----------+--------------+----------------+---------------------------------------------------------------------- | 0 | Start | | | outputVar: [{"colNames":[],"name":"__Start_0","type":"DATASET"}] | -----+----------+--------------+----------------+----------------------------------------------------------------------
PROFILEnebula> PROFILE format="row" SHOW TAGS; +--------+ | Name | +--------+ | player | +--------+ | team | +--------+ Got 2 rows (time spent 2038/2728 us) Execution Plan -----+----------+--------------+----------------------------------------------------+---------------------------------------------------------------------- | id | name | dependencies | profiling data | operator info | -----+----------+--------------+----------------------------------------------------+---------------------------------------------------------------------- | 1 | ShowTags | 0 | ver: 0, rows: 1, execTime: 42us, totalTime: 1177us | outputVar: [{"colNames":[],"name":"__ShowTags_1","type":"DATASET"}] | | | | | | inputVar: | -----+----------+--------------+----------------------------------------------------+---------------------------------------------------------------------- | 0 | Start | | ver: 0, rows: 0, execTime: 1us, totalTime: 57us | outputVar: [{"colNames":[],"name":"__Start_0","type":"DATASET"}] | -----+----------+--------------+----------------------------------------------------+----------------------------------------------------------------------
The descriptions are as follows.
| Parameter | Description |
|---|---|
id |
The ID of the operator. |
name |
The name of the operator. |
dependencies |
The ID of the operator that the current operator depends on. |
profiling data |
The content of the execution profile. ver is the version of the operator. rows shows the number of rows to be output by the operator. execTime shows the execution time of action. totalTime is the sum of the execution time, the system scheduling time, and the queueing time. |
operator info |
The detailed information of the operator. |
The dot format¶
You can use the format="dot" option to output the return message in the dot language, and then use Graphviz to generate a graph of the plan.
Note
Graphviz is open source graph visualization software. Graphviz provides an online tool for previewing DOT language files and exporting them to other formats such as SVG or JSON. For more information, see Graphviz Online.
nebula> EXPLAIN format="dot" SHOW TAGS;
Execution succeeded (time spent 161/665 us)
Execution Plan
--------------------------------------------------------------------------------------------------------------------------------------------- -------------
plan
--------------------------------------------------------------------------------------------------------------------------------------------- -------------
digraph exec_plan {
rankdir=LR;
"ShowTags_0"[label="ShowTags_0|outputVar: \[\{\"colNames\":\[\],\"name\":\"__ShowTags_0\",\"type\":\"DATASET\"\}\]\l|inputVar:\l", shape=Mrecord];
"Start_2"->"ShowTags_0";
"Start_2"[label="Start_2|outputVar: \[\{\"colNames\":\[\],\"name\":\"__Start_2\",\"type\":\"DATASET\"\}\]\l|inputVar: \l", shape=Mrecord];
}
--------------------------------------------------------------------------------------------------------------------------------------------- -------------
The Graphviz graph transformed from the above DOT statement is as follows.
The tck format¶
The tck format is similar to a table, but without borders and dividing lines between rows. You can use the results as test cases for unit testing. For information on tck format test cases, see TCK cases.
EXPLAINnebula> EXPLAIN format="tck" FETCH PROP ON player "player_1","player_2","player_3" YIELD properties(vertex).name as name, properties(vertex).age as age; Execution succeeded (time spent 261µs/613.718µs) Execution Plan (optimize time 28 us) | id | name | dependencies | profiling data | operator info | | 2 | Project | 1 | | | | 1 | GetVertices | 0 | | | | 0 | Start | | | | Wed, 22 Mar 2023 23:15:52 CST
PROFILEnebula> PROFILE format="tck" FETCH PROP ON player "player_1","player_2","player_3" YIELD properties(vertex).name as name, properties(vertex).age as age; | name | age | | "Piter Park" | 24 | | "aaa" | 24 | | "ccc" | 24 | Got 3 rows (time spent 1.474ms/2.19677ms) Execution Plan (optimize time 41 us) | id | name | dependencies | profiling data | operator info | | 2 | Project | 1 | {"rows":3,"version":0} | | | 1 | GetVertices | 0 | {"resp[0]":{"exec":"232(us)","host":"127.0.0.1:9779","total":"758(us)"},"rows":3,"total_rpc":"875(us)","version":0} | | | 0 | Start | | {"rows":0,"version":0} | | Wed, 22 Mar 2023 23:16:13 CST