[Feature][Lakehouse] Support Iceberg catalog labels #68916

Search before asking

• I had searched in the issues and found no similar issues.

Description

Motivation

The Iceberg REST Catalog specification supports optional catalog-provided labels in table and view load responses. These labels describe attributes such as ownership, business domain, data classification, and cost attribution.

Doris should preserve and expose this information when users inspect Iceberg external tables and supported views. This would improve data discovery and provide useful context for governance integrations and analytics agents, without requiring separate integrations with each catalog’s proprietary metadata API.

Proposed implementation

1. Read and preserve labels

Support the standardized labels structure returned by loadTable and, where REST views are supported, loadView:

• object-labels: a string-to-string map describing the table or view.
• fields: an array containing field-id and a labels map for each labeled field.

Example response fragment:

{
  "labels": {
    "object-labels": {
      "owner": "analytics-team",
      "business-domain": "sales"
    },
    "fields": [
      {
        "field-id": 3,
        "labels": {
          "classification": "pii",
          "semantic-type": "email"
        }
      }
    ]
  }
}

The keys and values above are illustrative conventions; the Iceberg specification does not assign them predefined policy semantics.

2. Integrate labels into external metadata handling

• Retain labels in FE metadata objects, separately from Iceberg table properties and connection configuration.
• Associate field labels using Iceberg field IDs, resolving column names or paths for display.
• Preserve arbitrary keys and multiple labels per field.
• Handle unresolved field IDs safely, without attaching their labels to a different column.
• Refresh labels through the catalog’s load/refresh lifecycle, respecting response caching and authentication scope.

3. Expose labels through a metadata inspection interface

Provide a documented, read-only interface for retrieving object-level and field-level labels.

The output should include the catalog, namespace, object name and type, optional field ID, optional resolved column name or path, label key, and label value. Object-level labels should have no field ID.

The initial feature covers metadata retrieval and inspection. Label-based policy evaluation, inheritance, label-management operations, and propagation to native Doris tables can be addressed through separate integrations.

Acceptance criteria

• Object-level and field-level labels are available through the documented inspection interface.
• Catalogs that omit labels continue to work normally.
• Multiple labels and unfamiliar keys are preserved.
• Column renames retain the correct association through field IDs.
• Dropped or unresolved field IDs do not cause labels to be assigned incorrectly.
• Refreshing catalog metadata updates the exposed labels.
• Labels are kept separate from persisted Iceberg table metadata and connection configuration.
• Receiving labels alone does not change query results or introduce implicit authorization rules.

References

• [Iceberg labels specification: apache/iceberg#15750](REST Spec: add labels field for catalog metadata enrichment iceberg#15750)
• [Iceberg REST Catalog specification](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml)
• [Java labels response support: apache/iceberg#18045](Core: add labels to the load table/view read path iceberg#18045)
• [Java SupportsLabels interface: apache/iceberg#18046](Core: expose catalog labels on the loaded table via SupportsLabels iceberg#18046)

Use case

No response

Related issues

No response

Are you willing to submit PR?

• Yes I am willing to submit a PR!

Code of Conduct

• I agree to follow this project's Code of Conduct