An Iceberg 129 table is a tree of immutable files rooted in one metadata JSON file (Open Table Formats). The catalog holds the only mutable piece: for each table identifier, the location of its current metadata file. A commit is a compare-and-swap of that pointer, so the catalog is both the arbiter of concurrency and the place where engines discover tables. Around it, catalogs keep namespaces and views, and increasingly users, grants and storage credentials. The fixture keeps its pointers in SQLite 4,756 through Iceberg's JdbcCatalog:
# What the REST fixture's JDBC catalog stores for BookNest: one row per table, two pointers.
docker cp -q l1-iceberg-rest:/home/iceberg/catalog.db catalog.db
f() { echo "substr($1, instr($1, '/metadata/') + 10, 5) AS $2"; } # 0000N of the file name
sqlite3 -header catalog.db ".tables" "SELECT table_namespace AS ns, table_name,
$(f metadata_location current), $(f previous_metadata_location previous) FROM iceberg_tables"iceberg_namespace_properties iceberg_tables ns|table_name|current|previous booknest|books|00002|00001 booknest|orders|00004|00003 booknest|order_items|00002|00001
Three rows are the whole catalog, and the data in warehouse/ is unreachable without them: back up the catalog's database. If rows are lost, the REST register endpoint re-attaches a table from its latest metadata file.