Compact delete files

ReferenceApplies to: Unified engine deployments

Iceberg format v2 can record row changes in positional-delete files. Each delete entry identifies a row position in a data file. Delete compaction combines eligible delete files while preserving which rows readers should hide.

Before you start

Choose a writable Iceberg catalog in Workbench and an unused practice namespace. The table must support row deletes and format-v2 maintenance. This recipe uses only inline data and replaces maintenance_docs.delete_demo.

Create row changes, compact, and verify

The script writes six rows, deletes one row from each of two writes, compacts eligible positional-delete files, and checks the visible rows.

SET spark.sql.caseSensitive = true;
CREATE NAMESPACE IF NOT EXISTS maintenance_docs;
DROP TABLE IF EXISTS maintenance_docs.delete_demo;
CREATE TABLE maintenance_docs.delete_demo (
  id BIGINT,
  region STRING,
  amount BIGINT
) USING iceberg
TBLPROPERTIES ('format-version' = '2');

INSERT INTO maintenance_docs.delete_demo
VALUES (1, 'North', 10), (2, 'South', 20);
INSERT INTO maintenance_docs.delete_demo
VALUES (3, 'North', 30), (4, 'South', 40);
INSERT INTO maintenance_docs.delete_demo
VALUES (5, 'North', 50), (6, 'South', 60);

DELETE FROM maintenance_docs.delete_demo WHERE id = 2;
DELETE FROM maintenance_docs.delete_demo WHERE id = 5;

SELECT COUNT(*) AS row_count, SUM(amount) AS total_amount
FROM maintenance_docs.delete_demo;

CALL system.rewrite_position_delete_files(
  table => 'maintenance_docs.delete_demo',
  target_file_size_bytes => 1048576
);

SELECT COUNT(*) AS row_count, SUM(amount) AS total_amount
FROM maintenance_docs.delete_demo;
SELECT * FROM maintenance_docs.delete_demo ORDER BY id;

After the deletes and again after maintenance, the aggregate result should be:

row_count	total_amount
4	140

The remaining rows have IDs 1, 3, 4, and 6. Compaction must not bring IDs 2 or 5 back into the visible result.

Read the maintenance result

Select the CALL statement in Workbench’s results.

Result column	Meaning
`rewritten_delete_files_count`	Delete files replaced
`added_delete_files_count`	Replacement delete files added
`rewritten_bytes_count`	Bytes reported as rewritten by the provider

Refresh Catalogs → table → Inspection → Files and compare the delete-file entries before and after the operation. Exact counts depend on the delete writer and eligible files. If the table has no qualifying positional-delete files, a successful no-op is valid.

Understand what changes

Delete compaction reorganizes the files that describe deleted positions. It does not mean that deleted row values have been physically removed from every data file or old snapshot. The current action handles positional-delete files. Do not use it as an equality-delete rewrite, snapshot-expiry procedure, or orphan cleanup operation. Those are different operations with different support requirements. Use SQL queries for exact visible row counts. File metadata can contain overlapping delete entries, so subtracting delete entries from data-record totals is not an exact row-count calculation.

Clean up

After the operation completes, remove the practice table through the catalog:

DROP TABLE IF EXISTS maintenance_docs.delete_demo;

See data compaction for data-file layout and TBLPROPERTIES for later write settings.

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Before you start

Create row changes, compact, and verify

Read the maintenance result

Understand what changes

Clean up

​Before you start

​Create row changes, compact, and verify

​Read the maintenance result

​Understand what changes

​Clean up

Before you start

Create row changes, compact, and verify

Read the maintenance result

Understand what changes

Clean up