zeroshade commented on code in PR #2599:
URL: https://github.com/apache/iceberg-go/pull/2599#discussion_r4603704541


##########
website/src/api.md:
##########
@@ -855,6 +855,24 @@ newTbl, err := txn.Commit(ctx)
 
 Pass `table.WithPostCommit(true)` to delete the unreferenced data and metadata 
files after the commit lands. The `iceberg expire-snapshots` CLI command wraps 
the same operation - see [CLI](./cli.md).
 
+### Orphan cleanup
+
+Use `maintenance.PlanOrphanFiles` to inspect candidates before deleting files
+with `maintenance.ExecuteOrphanCleanup`. Execution removes exactly the planned
+files; it does not scan again. `maintenance.DeleteOrphanFiles` combines 
planning
+and deletion (or supports a dry run). The default age threshold is 72 hours.
+
+**Safety:** All three orphan-cleanup entry points reject
+`gc.enabled=false` and tables loaded by REST with
+`snapshot-loading-mode=refs`, including dry runs. Refs-only metadata may
+omit snapshots whose files are still live, so cleanup fails with
+`table.ErrInvalidOperation` (check with `errors.Is`) before touching
+the filesystem. Configure the REST server to load

Review Comment:
   For library users `snapshot-loading-mode` is a client catalog property (e.g. 
`rest.WithAdditionalProps`), not only a server setting. The server can force it 
via `/v1/config` overrides, which win over client props. Suggest something 
like: "Create the REST catalog with `snapshot-loading-mode=all` (or omit it); 
if the server forces `refs` through config overrides, orphan cleanup is not 
available through that catalog."



##########
website/src/api.md:
##########
@@ -855,6 +855,24 @@ newTbl, err := txn.Commit(ctx)
 
 Pass `table.WithPostCommit(true)` to delete the unreferenced data and metadata 
files after the commit lands. The `iceberg expire-snapshots` CLI command wraps 
the same operation - see [CLI](./cli.md).
 
+### Orphan cleanup

Review Comment:
   This page already has `### Orphan file cleanup` under `## Maintenance` 
(around line 773). Could the plan/execute description and the safety paragraph 
move into that section instead of adding a second orphan-cleanup heading?



##########
table/maintenance/orphan_cleanup.go:
##########
@@ -368,6 +372,9 @@ func ExecuteOrphanCleanup(ctx context.Context, tbl 
*table.Table, plan OrphanClea
        if cfg.invalidPlanOption != nil {
                return OrphanCleanupResult{}, cfg.invalidPlanOption
        }
+       if err := validateCompleteSnapshotHistory(tbl); err != nil {

Review Comment:
   nit: here the refs-only check runs before `validateOrphanCleanupGC`, while 
`DeleteOrphanFiles`/`PlanOrphanFiles` check GC first (refs-only is checked 
inside `planOrphanFiles`). A table with both conditions returns a different 
error depending on the entry point. Consider using the same order everywhere.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to