Core: add labels to the load table/view read path by laskoviymishka · Pull Request #17337 · apache/iceberg

laskoviymishka · 2026-07-22T15:46:24Z

Reference client implementation for the IRC labels read path, the Java-side counterpart to the spec change in #15750.

Why

The spec PR (#15750) adds an optional labels field to LoadTableResult and LoadViewResult. Without a corresponding client change, RESTObjectMapper (which sets FAIL_ON_UNKNOWN_PROPERTIES = false) silently drops the field on deserialization, so labels returned by a catalog are invisible to the Java client. This PR makes the reference client able to read and round-trip them.

What changed

New org.apache.iceberg.rest.labels package (laid out like rest.credentials):

Labels — object (catalog-object-level, flat string map) and fields (per-field labels).
FieldLabels — a single field's labels, identified by field-id.
LabelsParser / FieldLabelsParser — JSON serialization, symmetric with the spec schemas.

Wired an optional labels field into LoadTableResponse and LoadViewResponse and their parsers. Labels are omitted from the wire when absent, so the change is backward compatible — existing responses serialize identically.

Tests

TestLabelsParser: round-trips (object-only, fields-only, both), empty labels, and field-id validation.
roundTripSerdeWithLabels and labelsAreOptional added to TestLoadTableResponseParser and TestLoadViewResponseParser.

Notes

Draft, opened primarily to exercise CI.
Depends on the wire shape in REST Spec: add labels field for catalog metadata enrichment #15750; the object / fields naming follows the structure agreed on that PR.
Scope is the read path only. The write path (UpdateLabels) is a separate follow-up, consistent with the spec PR.

pvary · 2026-07-24T13:22:13Z

How will old REST clients react if there is a new labels in the response JSON?

laskoviymishka · 2026-07-24T14:15:12Z

@pvary -- they will simply ignore it.

pvary · 2026-07-24T15:11:12Z

It the spec change is accepted, this is good to go as well.

nastra · 2026-07-28T07:09:05Z

+@Value.Immutable
+public interface Labels {
+  /** Catalog-object-level labels, attached to the object (table, view, ...) as a whole. */
+  Map<String, String> object();


have we decided on the naming in the Spec for this? I still feel like object() is really not telling me anything as a reader of the code

We discuss this here - #15750 (comment)

I'm thinking we are close to alignment, i don't have strong preferences honestly, just want to ensure it works :)

nastra · 2026-07-29T06:51:23Z

+  }
+
+  @Test
+  public void emptyLabels() {


what about JSON that has empty or no labels defined?

Reference client implementation for the IRC labels read-path spec change (apache#15750). Without it, RESTObjectMapper (which sets FAIL_ON_UNKNOWN_PROPERTIES = false) silently drops the labels field on deserialization, so labels returned by a catalog are invisible to the Java client. New rest.labels package (mirroring rest.credentials): Labels (object + fields sub-scopes, with a shared empty instance) and FieldLabels (per-field, keyed by field-id) value types as immutables interfaces, each with a JSON parser. FieldLabels validates field-id >= 1 and a non-empty labels map, matching Credential. Wire an optional labels field into LoadTableResponse / LoadViewResponse and their parsers. labels() never returns null (empty instance when absent), on LoadViewResponse via a @Value.Default default method so no interface API break is introduced. Labels are omitted from the wire when absent (or empty), so the change is additive and backward compatible.

github-actions Bot added the core label Jul 22, 2026

laskoviymishka force-pushed the labels-client-impl branch from 8480d56 to 763bffa Compare July 23, 2026 14:50

laskoviymishka requested a review from nastra July 23, 2026 16:00

nastra requested review from pvary, singhpk234 and stevenzwu July 23, 2026 17:34