From 413e170feb1d98f98dab77c46d2b2c5ce92b4d8c Mon Sep 17 00:00:00 2001
From: findinpath <findinpath@gmail.com>
Date: Tue, 8 Feb 2022 18:08:12 +0100
Subject: [PATCH] Move `optimize` documentation in an own section

---
 docs/src/main/sphinx/connector/hive.rst | 44 ++++++++++++++++++-------
 1 file changed, 33 insertions(+), 11 deletions(-)

diff --git a/docs/src/main/sphinx/connector/hive.rst b/docs/src/main/sphinx/connector/hive.rst
index 82168c947a3b..0eed444610cc 100644
--- a/docs/src/main/sphinx/connector/hive.rst
+++ b/docs/src/main/sphinx/connector/hive.rst
@@ -688,24 +688,46 @@ ALTER TABLE EXECUTE
 ^^^^^^^^^^^^^^^^^^^
 
 The connector supports the following commands for use with
-:ref:`ALTER TABLE EXECUTE <alter-table-execute>`:
+:ref:`ALTER TABLE EXECUTE <alter-table-execute>`.
 
-* ``optimize``: collapse files in a non-transactional table up to a threshold
-  defined in the ``file_size_threshold`` parameter. For example, the following
-  statement collapses files in a table that are under 10 megabytes in size:
+optimize
+~~~~~~~~
 
-  .. code-block:: sql
+The ``optimize`` command is used for rewriting the content
+of the specified non-transactional table so that it is merged
+into fewer but larger files.
+In case that the table is partitioned, the data compaction
+acts separately on each partition selected for optimization.
+This operation improves read performance.
+
+All files with a size below the optional ``file_size_threshold``
+parameter (default value for the threshold is ``100MB``) are
+merged:
+
+.. code-block:: sql
+
+    ALTER TABLE test_table EXECUTE optimize
+
+The following statement merges files in a table that are
+under 10 megabytes in size:
+
+.. code-block:: sql
 
     ALTER TABLE test_table EXECUTE optimize(file_size_threshold => '10MB')
 
-  You can use a ``WHERE`` clause with the columns used to partition the table,
-  to filter which partitions are optimized.
+You can use a ``WHERE`` clause with the columns used to partition the table,
+to filter which partitions are optimized:
+
+.. code-block:: sql
+
+    ALTER TABLE test_partitioned_table EXECUTE optimize
+    WHERE partition_key = 1
 
-  The ``optimize`` procedure is disabled by default, and can be enabled for a
-  catalog with the ``<catalog-name>.non_transactional_optimize_enabled``
-  session property:
+The ``optimize`` command is disabled by default, and can be enabled for a
+catalog with the ``<catalog-name>.non_transactional_optimize_enabled``
+session property:
 
-  .. code-block:: sql
+.. code-block:: sql
 
     SET SESSION <catalog_name>.non_transactional_optimize_enabled=true