korlov42 commented on code in PR #6163: URL: https://github.com/apache/ignite-3/pull/6163#discussion_r2182004046
########## docs/_docs/sql-reference/explain-statement.adoc: ########## @@ -0,0 +1,257 @@ +// Licensed to the Apache Software Foundation (ASF) under one or more +// contributor license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright ownership. +// The ASF licenses this file to You under the Apache License, Version 2.0 +// (the "License"); you may not use this file except in compliance with +// the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. += EXPLAIN Command + +The `EXPLAIN` command is used to display the execution plan of a SQL query, showing how the query will be processed by the sql engine. +It provides insights into the relational operators used, their configuration, and the estimated number of rows processed at each step. +This information is essential for diagnosing performance bottlenecks and understanding query optimization decisions. + +== Syntax + +[.diagram-container] +Diagram( + Terminal('EXPLAIN'), + Optional( + Sequence( + Choice( + 0, + Terminal('PLAN'), + Terminal('MAPPING') + ), + Terminal('FOR') + ) + ), + NonTerminal('query_or_dml') +) + +If neither `PLAN` nor `MAPPING` is specified, then `PLAN` is implicit. + +Parameters: + +- `PLAN` - explains query in terms of relational operators tree. +This representation is suitable for investigation of performance issues related to the optimizer. + +- `MAPPING` - explains query in terms of mapping of query fragment to a particular node of the cluster. +This representation is suitable for investigation of performance issues related to the data colocation. + +Examples: + +[source,sql] +---- +EXPLAIN SELECT * FROM lineitem; +EXPLAIN PLAN FOR SELECT * FROM lineitem; +EXPLAIN MAPPING FOR SELECT * FROM lineitem; +---- + +== Understanding The Output + +Each query plan is represented as a tree-like structure composed of **relational operators**. Review Comment: done ########## docs/_docs/sql-reference/explain-statement.adoc: ########## @@ -0,0 +1,257 @@ +// Licensed to the Apache Software Foundation (ASF) under one or more +// contributor license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright ownership. +// The ASF licenses this file to You under the Apache License, Version 2.0 +// (the "License"); you may not use this file except in compliance with +// the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. += EXPLAIN Command + +The `EXPLAIN` command is used to display the execution plan of a SQL query, showing how the query will be processed by the sql engine. +It provides insights into the relational operators used, their configuration, and the estimated number of rows processed at each step. +This information is essential for diagnosing performance bottlenecks and understanding query optimization decisions. + +== Syntax + +[.diagram-container] +Diagram( + Terminal('EXPLAIN'), + Optional( + Sequence( + Choice( + 0, + Terminal('PLAN'), + Terminal('MAPPING') + ), + Terminal('FOR') + ) + ), + NonTerminal('query_or_dml') +) + +If neither `PLAN` nor `MAPPING` is specified, then `PLAN` is implicit. + +Parameters: + +- `PLAN` - explains query in terms of relational operators tree. +This representation is suitable for investigation of performance issues related to the optimizer. + +- `MAPPING` - explains query in terms of mapping of query fragment to a particular node of the cluster. +This representation is suitable for investigation of performance issues related to the data colocation. + +Examples: + +[source,sql] +---- +EXPLAIN SELECT * FROM lineitem; +EXPLAIN PLAN FOR SELECT * FROM lineitem; +EXPLAIN MAPPING FOR SELECT * FROM lineitem; +---- + +== Understanding The Output + +Each query plan is represented as a tree-like structure composed of **relational operators**. + +A node in the plan includes: + +- A **name**, indicating the relational operator (e.g., `TableScan`, `IndexScan`, `Sort`, `Join` types) +- A set of **attributes**, relevant to that specific operator + +[source,text] +---- +OperatorName + attribute1: value1 + attribute2: value2 +---- + +Examples: + +[source,text] +---- +TableScan // Full table access + table: PUBLIC.EMP + fieldNames: [NAME, SALARY] + est: (rows=1) + +IndexScan // Index-based access + table: PUBLIC.EMP + index: EMP_NAME_DESC_IDX + type: SORTED + fields: [NAME] + collation: [NAME DESC] + est: (rows=1) + +Sort // Sort rows + collation: [NAME DESC NULLS LAST] + est: (rows=1) +---- + +=== Operator Naming + +The operator name reflects the specific algorithm or strategy used. +For example: + +- `TableScan` – Full scan of a base table +- `IndexScan` – Access via index, possibly sorted +- `Sort` – Explicit sorting step +- `HashJoin`, `MergeJoin`, `NestedLoopJoin` – Types of join algorithms +- `Limit`, `Project`, `Exchange` – Execution-related transformations and controls + +=== Hierarchical Plan Structure + +The plan is structured as a **tree**, where: + +- **Leaf nodes** represent data sources (e.g., `TableScan`) +- **Internal nodes** represent data transformations (e.g., `Join`, `Sort`) +- **The root node** (topmost) is the final operator that produces the result + +=== Example: Complex Join + +[source,sql] +---- +EXPLAIN SELECT + U.UserName, P.ProductName, R.ReviewText, R.Rating + FROM Users U, Reviews R, Products P + WHERE U.UserID = R.UserID + AND R.ProductID = P.ProductID + AND P.ProductName = 'Product_' || ?::varchar +---- + +The resulting output is: + +[example] Review Comment: done -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@ignite.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
