diff --git a/docs/web/basics/guarantees.mdx b/docs/web/basics/guarantees.mdx index b3c139e99..ebe7dbb14 100644 --- a/docs/web/basics/guarantees.mdx +++ b/docs/web/basics/guarantees.mdx @@ -77,11 +77,13 @@ exists. Retention is finite. [Cleanup](/maintenance/cleanup) prunes versions older than the retention window — **7 days by default** for `optimize()` in the embedded library, while a deployment's configuration sets its own. It always -keeps the latest version, the versions branches were forked from and tagged -versions. A tagged version that is older than the window and is not the latest -stops cleanup altogether, until the tag is moved inside the window or deleted, -or the window is widened. If you rely on reading old versions, widen the window -before running it, not after. +keeps the latest version and tagged versions. It also keeps the files a branch +still reads, and the version the branch was forked from while the branch's +remaining versions read the parent's files; after that, the fork version is +pruned like any other. A tagged version that is older than the window and is +not the latest stops cleanup altogether, until the tag is moved inside the +window or deleted, or the window is widened. If you rely on reading old +versions, tag them or widen the window before running it, not after. **Dropping a table ends its history.** Versioning does not survive diff --git a/docs/web/maintenance/cleanup.mdx b/docs/web/maintenance/cleanup.mdx index ede712b2e..bd5b04731 100644 --- a/docs/web/maintenance/cleanup.mdx +++ b/docs/web/maintenance/cleanup.mdx @@ -40,8 +40,8 @@ removed, along with the files only they referenced. On a deployment, the retention period comes from its configuration instead. The latest version is never removed, whatever you pass. `timedelta(0)` makes -every older version eligible for removal, but cleanup still keeps the versions -that branches and tags protect, as the warning below describes. +every older version eligible for removal, but cleanup still keeps tagged +versions and the files branches still read, as the warning below describes. Pruning is what makes [time travel](/management/table#versioning) finite: an @@ -49,10 +49,15 @@ eligible version outside the retention window is gone. Cleanup keeps a version, whatever its age, when it is: - the **latest** version; -- a version a **branch** was forked from, along with the files the branch - reads; the parent's other old versions are pruned as usual; - a **tagged** version. +Cleanup also keeps the files a **branch** still reads, and the version the +branch was forked from while the branch's remaining versions read the parent's +files. That does not keep the fork for good: once the branch has replaced the +data it inherited and its own older versions are pruned, cleanup prunes the +fork version like any other. To keep a version recoverable, tag it, subject to +the policy below, or keep the window wide enough to cover it. + Under the default policy, a tag can also stop cleanup. When a tagged version is older than the window and is not the latest, cleanup refuses to run: it raises an error naming the tag and prunes nothing. To let it proceed, move the tag to a