From f40b9da8f17a54b21d800d4a33aaeacae7db783d Mon Sep 17 00:00:00 2001
From: Steve Burnett <burnett@pobox.com>
Date: Thu, 10 Oct 2024 17:32:19 -0400
Subject: [PATCH] Add documentation for query plan and plan fragment

---
 .../src/main/sphinx/overview/concepts.rst     | 27 +++++++++++++++++++
 presto-docs/src/main/sphinx/sql/explain.rst   |  8 +++---
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/presto-docs/src/main/sphinx/overview/concepts.rst b/presto-docs/src/main/sphinx/overview/concepts.rst
index 66ea9128c7d8f..ec9159127d034 100644
--- a/presto-docs/src/main/sphinx/overview/concepts.rst
+++ b/presto-docs/src/main/sphinx/overview/concepts.rst
@@ -183,6 +183,33 @@ that statement. A query encompasses stages, tasks, splits, connectors,
 and other components and data sources working in concert to produce a
 result.
 
+Query Plan
+^^^^^^^^^^
+
+A query plan is an `operator <https://prestodb.io/docs/current/overview/concepts.html#operator>`_ 
+- a sequence of steps used to access and manipulate data according to the SQL 
+query. It is represented as a tree of nodes, with each node representing a 
+logical unit of relational algebra that can be executed by the. engine. 
+Because query plans can have different performance behavior, Presto uses 
+a query optimizer to make query plans more efficient.
+
+There are two phases of optimization: logical and physical. The logical 
+phase of optimization transforms plans by only considering algorithmic 
+complexity. The logically optimized query plan is then converted into 
+a physical query plan, which is optimized for distributed execution and 
+includes details such as the number and 
+`types <https://prestodb.io/docs/current/overview/concepts.html#server-types>`_ 
+of Presto servers which should process a query plan node, and how data is 
+`exchanged <https://prestodb.io/docs/current/overview/concepts.html#exchange>`_ 
+between them.
+
+Plan Fragment
+^^^^^^^^^^^^^
+
+A plan fragment is a section of the physical query plan executed by 
+`tasks <https://prestodb.io/docs/current/overview/concepts.html#task>`_ on different 
+`Presto servers <https://prestodb.io/docs/current/overview/concepts.html#server-types>`_.
+
 Stage
 ^^^^^
 
diff --git a/presto-docs/src/main/sphinx/sql/explain.rst b/presto-docs/src/main/sphinx/sql/explain.rst
index e4c9144726e4a..1b541b1d82e9a 100644
--- a/presto-docs/src/main/sphinx/sql/explain.rst
+++ b/presto-docs/src/main/sphinx/sql/explain.rst
@@ -20,10 +20,10 @@ Description
 -----------
 
 Show the logical or distributed execution plan of a statement, or validate the statement.
-Use ``TYPE DISTRIBUTED`` option to display fragmented plan. Each plan fragment is executed by
-a single or multiple Presto nodes. Fragments separation represent the data exchange between Presto nodes.
-Fragment type specifies how the fragment is executed by Presto nodes and how the data is
-distributed between fragments:
+Use ``TYPE DISTRIBUTED`` option to display fragmented plan. Each 
+`plan fragment <https://prestodb.io/docs/current/overview/concepts.html#plan-fragment>`_ 
+is executed by a single or multiple Presto nodes. Fragment type specifies how the fragment 
+is executed by Presto nodes and how the data is distributed between fragments:
 
 ``SINGLE``
     Fragment is executed on a single node.