[docs] Clarify that empty partition directories are not deleted by default (#8304)

Author: lilei1128

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  

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:

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)