Document OPTIMIZE for Iceberg

docs/src/main/sphinx/connector/iceberg.rst

@@ -130,6 +130,48 @@ supports the following features:
 
 .. include:: alter-mv-set-properties-unsupported.fragment
 
+.. _iceberg-alter-table-execute:
+
+ALTER TABLE EXECUTE
+^^^^^^^^^^^^^^^^^^^
+
+The connector supports the following commands for use with
+:ref:`ALTER TABLE EXECUTE <alter-table-execute>`.
+
+optimize
+~~~~~~~~
+
+The ``optimize`` command is used for rewriting the active content
+of the specified 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 the 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 apply ``optimize`` only on the partition(s) corresponding
+to the filter:
+
+.. code-block:: sql
+
+    ALTER TABLE test_partitioned_table EXECUTE optimize
+    WHERE partition_key = 1
+
 .. _iceberg-type-mapping:
 
 Type mapping