From b3e3452973dba967b7b5209aa28ac29e07ee73bb Mon Sep 17 00:00:00 2001
From: Joe Lodin <joe.lodin@starburstdata.com>
Date: Mon, 18 Oct 2021 17:08:03 -0400
Subject: [PATCH] Document ALTER TABLE EXECUTE commands

---
 docs/src/main/sphinx/connector/hive.rst  | 39 ++++++++++++++++++++++++
 docs/src/main/sphinx/sql/alter-table.rst | 17 +++++++++++
 2 files changed, 56 insertions(+)

diff --git a/docs/src/main/sphinx/connector/hive.rst b/docs/src/main/sphinx/connector/hive.rst
index 21d67ab3247b..c436d276bab6 100644
--- a/docs/src/main/sphinx/connector/hive.rst
+++ b/docs/src/main/sphinx/connector/hive.rst
@@ -660,6 +660,45 @@ features:
 
 * :ref:`sql-security-operations`, see also :ref:`hive-sql-standard-based-authorization`
 
+.. _hive-alter-table-execute:
+
+ALTER TABLE EXECUTE
+^^^^^^^^^^^^^^^^^^^
+
+The connector supports the following commands for use with
+:ref:`ALTER TABLE EXECUTE <alter-table-execute>`:
+
+* ``optimize``: collapse files in transactional tables 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:
+
+  .. 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.
+
+  The ``optimize`` procedure is disabled by default, and can be enabled for a
+  catalog with the ``<catalog-name>.non_transactional_optimize_enabled``
+  session property:
+
+  .. code-block:: sql
+
+    SET SESSION <catalog_name>.non_transactional_optimize_enabled=true
+
+.. warning::
+
+  Because Hive tables are non-transactional, take note of the following possible
+  outcomes:
+
+  * If queries are run against tables that are currently being optimized,
+    duplicate rows may be read.
+  * In rare cases where exceptions occur during the ``optimize`` operation,
+    a manual cleanup of the table directory is needed. In this situation, refer
+    to the Trino logs and query failure messages to see which files need to be
+    deleted.
+
 .. _hive-data-management:
 
 Data management
diff --git a/docs/src/main/sphinx/sql/alter-table.rst b/docs/src/main/sphinx/sql/alter-table.rst
index 3ac68c0ca249..8a46ac3ccb17 100644
--- a/docs/src/main/sphinx/sql/alter-table.rst
+++ b/docs/src/main/sphinx/sql/alter-table.rst
@@ -15,6 +15,8 @@ Synopsis
     ALTER TABLE [ IF EXISTS ] name RENAME COLUMN [ IF EXISTS ] old_name TO new_name
     ALTER TABLE name SET AUTHORIZATION ( user | USER user | ROLE role )
     ALTER TABLE SET PROPERTIES ( property_name = expression [, ...] )
+    ALTER TABLE name EXECUTE command [ ( parameter => expression [, ... ] ) ]
+        [ WHERE expression ]
 
 Description
 -----------
@@ -27,6 +29,16 @@ The optional ``IF EXISTS`` (when used before the column name) clause causes the
 
 The optional ``IF NOT EXISTS`` clause causes the error to be suppressed if the column already exists.
 
+.. _alter-table-execute:
+
+EXECUTE
+^^^^^^^
+
+The ``ALTER TABLE EXECUTE`` statement followed by a ``command`` and
+``parameters`` modifies the table according to the specified command and
+parameters. ``ALTER TABLE EXECUTE`` supports different commands on a
+per-connector basis.
+
 Examples
 --------
 
@@ -74,6 +86,11 @@ Set table properties (``x=y``) to table ``users``::
 
     ALTER TABLE people SET PROPERTIES (x = 'y')
 
+Collapse files in a table that are over 10 megabytes in size, as supported by
+the Hive connector::
+
+    ALTER TABLE hive.schema.test_table EXECUTE optimize(file_size_threshold => `10MB`)
+
 See also
 --------