Skip to content

Core: Add a filesystem-only HadoopCatalog - #4450

Open
Anurag-S1ngh wants to merge 2 commits into
apache:mainfrom
Anurag-S1ngh:feat/3897-hadoop-catalog
Open

Anurag-S1ngh wants to merge 2 commits into
apache:mainfrom
Anurag-S1ngh:feat/3897-hadoop-catalog

Conversation

@Anurag-S1ngh

Copy link
Copy Markdown
Contributor

Rationale for this change

Add pyiceberg.catalog.hadoop.HadoopCatalog, a filesystem-only catalog with the same layout as the Java HadoopCatalog: tables live under <warehouse>/<namespace>/<table>, metadata is written as v{n}.metadata.json, and version-hint.text points at the current version. When the hint is missing or stale, the latest metadata file is found by listing the metadata directory, which also opens tables named with the 00000-<uuid>.metadata.json convention used by the REST and SQL catalogs.

Namespaces map to directories and have no stored properties, matching Java. Rename, registration, views, and namespace property updates are not supported.

New catalog type: type=hadoop with a warehouse property.

Are these changes tested?

Yes. tests/catalog/test_hadoop.py covers create, load, append, commit, version-hint updates, uuid-named metadata without a hint, stale hints, nested namespaces, listing, drop rules, custom locations, and unsupported operations. tests/catalog/test_base.py passes.

Are there any user-facing changes?

Yes. A new HadoopCatalog and the hadoop catalog type are available.

Store tables under warehouse/<namespace>/<table> with metadata in
v{n}.metadata.json and a version-hint.text, matching the Java
HadoopCatalog. Read the latest metadata by following the hint and falling
back to listing the metadata directory, so tables named with the uuid
metadata convention can be opened too.

Namespaces map to directories and carry no properties. Renames, views,
registration, and namespace properties are not supported, the same as the
Java catalog.
Rename the metadata writer so it does not override the base helper with a
different signature, match the register_table signature, and cast the
format version for the schema conversion.


class HadoopCatalog(MetastoreCatalog):
"""A filesystem-only catalog that stores tables under a warehouse directory.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Filesystem tables are considered unsafe and are deprecated in the next version of the spec: https://github.com/apache/iceberg/blob/main/format/spec.md#file-system-tables

I would like to avoid add it

@Anurag-S1ngh

Copy link
Copy Markdown
Contributor Author

I can drop this if the catalog is not wanted. Before I do, is the objection the commit scheme itself, or running it on object stores and local filesystems? The spec marks it unsafe there and removes it in v4, but HDFS atomic rename is the case Java's HadoopCatalog covers, and Java still ships it. If a version that only commits over HDFS and fails on file:// and object stores is acceptable, I will rescope.

@Fokko

Fokko commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

The problem is that the underlying object store requires very specific semantics. IIRC it is safe with S3, but not with GCS. The project realised that having object-store only catalogs isn't a feasible path forward. Apart from the correctness issues, it also had performance issues because it still relied on listing in some occasions.

For local testing an in-memory catalog works just as well, with stronger semantics. Hadoop tables can still be read using the StaticTable.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants