How to View Apache Iceberg Table Metadata Without Spark or Trino

July 3, 2026 · 5 min read

Apache Iceberg's biggest strength — rich, versioned metadata — is also its most frustrating property when you just want to lookat a table. The standard answer is "query it through Spark or Trino", which means standing up a cluster and configuring a catalog just to answer questions like what snapshots exist? or when did this column get added?

The good news: everything Iceberg knows about a table lives in plain files you can inspect directly.

Where Iceberg keeps its metadata

An Iceberg table directory has two parts:

my_table/
├── data/                          # Parquet/ORC/Avro data files
└── metadata/
    ├── v1.metadata.json           # table metadata (schema, snapshots, partition spec)
    ├── v2.metadata.json           # one per commit
    ├── snap-843...avro            # manifest list, one per snapshot
    └── 0e2f...-m0.avro            # manifests (lists of data files + stats)

The *.metadata.json file is the entry point. It is ordinary JSON containing the current schema, every schema version that ever existed, the partition spec, table properties, and the full snapshot log with timestamps and operation types (append, overwrite, delete).

Option 1: read metadata.json directly

For quick questions, cat and jq go a long way:

# Current schema
jq '.schemas[-1]' v3.metadata.json

# Snapshot history with timestamps
jq '.snapshots[] | {id: ."snapshot-id", ts: ."timestamp-ms", op: .summary.operation}' v3.metadata.json

This answers schema and history questions, but manifests (which data files exist, row counts, column bounds) are Avro files — not human-readable.

Option 2: PyIceberg (no cluster, but a Python environment)

from pyiceberg.table import StaticTable

table = StaticTable.from_metadata("s3://bucket/my_table/metadata/v3.metadata.json")
print(table.schema())
print(table.history())

StaticTable reads a table straight from its metadata file with no catalog service. You still need Python, PyIceberg, and file-system credentials configured.

Option 3: inspect it in your browser

If you just need to see the table — schema, snapshots, partition spec, manifest summaries — the Hexabench Iceberg Metadata Viewer renders all of it from your metadata files with zero environment setup. Point it at the table and browse snapshots and schema history the way you would browse a git log.

What to look for when debugging

Three metadata questions solve most Iceberg incidents:

1. Did a snapshot appear when the pipeline claimed to write?Check the snapshot log's timestamps and operations. A missing append snapshot means the commit failed after data files were written — orphan files, not table corruption.

2. Which schema version does a reader see?Every schema that ever existed is retained with an ID. Readers pinned to an old snapshot read with that snapshot's schema — the classic cause of "column does not exist" errors that only some jobs hit.

3. How many data files does a snapshot reference? Manifest summaries expose file counts. Thousands of small files in one snapshot explains slow scans better than any query profile.

Try the Iceberg Metadata Viewer → · Back to Blog