This is an automated email from the ASF dual-hosted git repository.
JingsongLi pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/paimon.git
The following commit(s) were added to refs/heads/master by this push:
new b8726cf352 [docs] Clarify that empty partition directories are not
deleted by default (#8304)
b8726cf352 is described below
commit b8726cf352018dbd4ca721e948a957edd3aef313
Author: sanshi <[email protected]>
AuthorDate: Mon Jun 22 18:07:10 2026 +0800
[docs] Clarify that empty partition directories are not deleted by default
(#8304)
---
docs/docs/learn-paimon/understand-files.mdx | 4 +++-
docs/docs/maintenance/manage-partitions.md | 5 +++++
docs/docs/maintenance/manage-snapshots.mdx | 9 +++++++++
3 files changed, 17 insertions(+), 1 deletion(-)
diff --git a/docs/docs/learn-paimon/understand-files.mdx
b/docs/docs/learn-paimon/understand-files.mdx
index 10c993a3e4..5d0a81296a 100644
--- a/docs/docs/learn-paimon/understand-files.mdx
+++ b/docs/docs/learn-paimon/understand-files.mdx
@@ -367,7 +367,9 @@ Let's say all 4 snapshots in the above diagram are about to
expire. The expire p
3. Finally, it deletes the snapshots themselves and writes the earliest hint
file.
-If any directories are left empty after the deletion process, they will be
deleted as well.
+If any directories are left empty after the deletion process, they will be
deleted as well,
+but only when `snapshot.clean-empty-directories` is enabled (default is
`false`).
+By default, empty directories are kept on disk. See [Manage
Snapshots](../maintenance/manage-snapshots#expire-snapshots).
Let's say another snapshot, `snapshot-5` is created and snapshot expiration is
triggered. `snapshot-1` to `snapshot-4` are
diff --git a/docs/docs/maintenance/manage-partitions.md
b/docs/docs/maintenance/manage-partitions.md
index 1570cdf8d2..b5a471a6b9 100644
--- a/docs/docs/maintenance/manage-partitions.md
+++ b/docs/docs/maintenance/manage-partitions.md
@@ -49,6 +49,11 @@ __Note:__ After the partition expires, it is logically
deleted and the latest sn
files in the file system are not immediately physically deleted, it depends on
when the corresponding snapshot expires.
See [Expire Snapshots](./manage-snapshots#expire-snapshots).
+Also, even after the data files are physically deleted by snapshot expiration,
the empty partition directories are
+**not** removed by default. To clean up empty directories, set
+`'snapshot.clean-empty-directories' = 'true'` on the table. Please note that
on object stores (e.g. OSS, S3)
+this may cause performance issues, which is why the option defaults to `false`.
+
:::
An example for single partition field:
diff --git a/docs/docs/maintenance/manage-snapshots.mdx
b/docs/docs/maintenance/manage-snapshots.mdx
index 821aa0b755..db2d9095be 100644
--- a/docs/docs/maintenance/manage-snapshots.mdx
+++ b/docs/docs/maintenance/manage-snapshots.mdx
@@ -83,11 +83,20 @@ Snapshot expiration is controlled by the following table
properties.
<td>Integer</td>
<td>The maximum number of snapshots allowed to expire at a time.</td>
</tr>
+ <tr>
+ <td><h5>snapshot.clean-empty-directories</h5></td>
+ <td>No</td>
+ <td style={{wordWrap: "break-word"}}>false</td>
+ <td>Boolean</td>
+ <td>Whether to try to delete empty directories (e.g. partition and
bucket directories) left behind after the data files are deleted during
snapshot expiration. Defaults to <code>false</code>: empty directories are
kept. Enabling it has caveats: HDFS may print exceptions in NameNode, and
object stores (OSS/S3) may suffer performance issues due to the extra prefix
operations required to list and delete directory markers.</td>
+ </tr>
</tbody>
</table>
When the number of snapshots is less than `snapshot.num-retained.min`, no
snapshots will be expired(even the condition `snapshot.time-retained` meet),
after which `snapshot.num-retained.max` and `snapshot.time-retained` will be
used to control the snapshot expiration until the remaining snapshot meets the
condition.
+Note that snapshot expiration is also what physically deletes data files
dropped by [partition expiration](./manage-partitions#expiring-partitions).
However, the empty partition and bucket directories left behind after the data
files are deleted are **not** removed by default. To clean them up, enable
`snapshot.clean-empty-directories` (see the option above). This is off by
default because on object stores (OSS/S3) the prefix operations needed to
delete directory markers can be expensive.
+
The following example show more details(`snapshot.num-retained.min` is 2,
`snapshot.time-retained` is 1h, `snapshot.num-retained.max` is 5):
> snapshot item is described using tuple (snapshotId, corresponding time)
