Table and Column Label Metadata in Iceberg REST Catalog
- Dominant language
- Java
- Stars
- 9.2k
- Forks
- 3.5k
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 132
Description
### Proposed Change
### Proposed Change
`LoadTableResponse` returns table metadata—schema, snapshots, file locations—but no way for the catalog to communicate the context it maintains around that table: ownership, classification, cost attribution, domain. That context lives in each catalog's own systems. Without a standard field for it, catalogs resort to vendor-specific extensions that OSS engines can't consume.
This proposal adds an optional `labels` field to `LoadTableResponse` for catalog-managed metadata. Labels are string key-value pairs generated per-request from the catalog's internal systems. Nothing is written to table files. Engines may use or ignore them entirely.
For example: a catalog tracks cost attribution and ownership — those labels travel with every table load without requiring a table commit. A consuming engine or AI agent reads domain and classification labels to understand what the table contains and apply its own policies accordingly. At the column level, catalogs can surface semantic metadata — what a column means, how it's classified in a data model — referenced by field ID so labels stay accurate across schema evolution.
### Goals
- Add optional `labels` field to `LoadTableResponse` in the REST Catalog spec
- Support table-level and column-level labels
- Column labels reference columns by field ID, stable across schema evolution
- Define OpenAPI schema for the `Labels` object
### Non-Goals
- No changes to table metadata files or the Iceberg table format
- No registry of label keys — catalogs define and document their own schemas
- No enforcement semantics — labels carry context, not decisions
### Proposal document
https://docs.google.com/document/d/1aj-6JlfBiMYEEVtNuh5WLMOrRQiMCcyYUGbouPM4hXI/edit?tab=t.0
### Specifications
- [ ] Table
- [ ] View
- [x] REST
- [ ] Puffin
- [ ] Encryption
- [ ] Other
Contributor guide
Research direction
Start with the linked proposal document and the Iceberg REST Catalog specification, focusing on LoadTableResponse and its OpenAPI definitions. Define the optional table- and column-level labels, using field IDs for column references, and complete the REST specification checklist without changing table metadata files or the table format.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, openapi
- Domain
- api, databases
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100