Inspect and prepare a table

ReferenceApplies to: Unified engine deployments

Inspect the table before choosing maintenance. Keep a small set of before-and-after measurements so you can explain what changed.

Before you start

Select a writable Iceberg catalog in Workbench. You need namespace and table creation, reads, writes, and the provider’s maintenance support. The examples create format-v2 tables and use inline data. Choose an unused practice namespace. The examples use maintenance_docs; replace it everywhere if that name is already used for other work. Each recipe uses its own table. A recipe’s setup drops and recreates only that recipe’s named practice table.

Create a small inspection table

Choose your catalog in Workbench and run the statements in order. The statements run in order as separate operations. They do not form one transaction.

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

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

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

Expected query result:

row_count	total_amount
6	210

The separate inserts give you several writes to inspect. Actual file counts depend on the writer and its settings.

Inspect the physical layout

Open the table under Catalogs, then open Inspection. Use its Summary, Snapshots, History, and Files sections where the connector supports them.

Record	Why it matters
Current snapshot ID	Identifies the version you inspected
Data-file count and bytes	Shows how many data files serve that version
Delete-file count and bytes	Shows the amount of delete metadata
Per-file size and record counts	Helps identify many small files or uneven layout
Snapshot and history entries	Helps distinguish your operation from other writes
Query row count and business totals	Checks the logical result visible to readers

Check all result pages when inspecting files. A single page is not necessarily the full table. Keep the selected snapshot explicit when comparing its file list, then refresh to the current snapshot after maintenance completes. Metadata record counts are not always visible row counts. A delete record may refer to a row already covered by another delete file. Do not subtract delete entries from data records to calculate the exact visible rows. Use a table query for that check.

Check table settings

SHOW TBLPROPERTIES maintenance_docs.inspect_demo;
DESCRIBE TABLE EXTENDED maintenance_docs.inspect_demo;

SHOW TBLPROPERTIES returns saved properties. DESCRIBE TABLE EXTENDED gives additional table details. Iceberg’s format version is table metadata, rather than an ordinary custom property; do not assume it appears as a normal key in every properties result.

Choose what to do next

Combine small data files with data compaction.
Combine positional-delete files with delete compaction.
Reorganize manifest metadata with manifest optimization.
Change defaults for future writes with TBLPROPERTIES.

Each recipe contains its own setup, maintenance call, row checks, and cleanup. You can run one without first creating this inspection table.

Clean up

DROP TABLE IF EXISTS maintenance_docs.inspect_demo;

This removes the table through the catalog’s normal drop behavior. It is not an orphan-file cleanup command. Keep the namespace while you are using the other recipes.

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Inspect and prepare a table

Before you start

Create a small inspection table

Inspect the physical layout

Check table settings

Choose what to do next

Clean up

​Before you start

​Create a small inspection table

​Inspect the physical layout

​Check table settings

​Choose what to do next

​Clean up

Before you start

Create a small inspection table

Inspect the physical layout

Check table settings

Choose what to do next

Clean up