# How to delete content and reclaim space

Remove catalog references and delete the payload in an application transaction.
Compact separately if the database file must stop carrying unreachable data.

Before deleting, check references in your application’s records outside the catalog.
xitstash cannot check them for you.

## Delete the file and payload together

Inside the write transaction, use the store’s write cursor as `store`.
Use the file record and revision from the deletion request as `file`:

```clojure
(objects/remove! store (:id file) (:revision file))
(objects/delete-payload! store (:digest file))
```

Let errors escape the callback.
If another catalog file references the payload, `delete-payload!` throws `:xitstash/conflict`.
Aborting the transaction restores the file removed by the preceding call too.

If there is no catalog file, call `delete-payload!` directly with the digest.

A successful call returns the digest and distinct chunk counts:

```clojure
{:digest "f1220..."
 :removed-chunks 3
 :shared-chunks 2}
```

The abbreviated digest illustrates the result shape.
Shared chunks continue to serve other payloads.

After commit, `payload` for the deleted digest must throw `:xitstash/not-found`.
Deletion does not revoke an already-open stream.

## Reclaim unreachable bytes

1. Stop access that could race with compaction or database replacement.
Close affected streams.
2. Remove old native snapshots if their bytes must no longer be copied.
If those snapshots must stay readable, expect their content in the compacted database.
3. Use xitdb’s `Database.compact` to write a separate target.
With an adapter, use its compaction API rather than bypassing its database coordination.
4. Reopen the target and verify the application records and payloads that should survive.
5. Replace the active database using your application’s file-replacement policy.
Dispose of the original only after validation.

The original file can still contain deleted bytes.
Backups, replicas and filesystem snapshots need separate handling.
Neither deletion nor compaction promises secure overwrite.

For xitdb-clj, `xdb/compact` copies the latest value with at most one history entry.
The Yggdrasil adapter instead preserves reachable commits.
See [Content and history](content-and-history.adoc) before choosing which history to discard.

For unusually large manifests, pass the same `:max-chunks` and `:max-metadata-bytes` budgets used to read them.
The defaults are listed in [`delete-payload!`](api/ol-xitstash.adoc#delete-payload-BANG-).