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-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.

Adds an `include-labels` flag to the REST server test fixture that attaches labels to load table and load view responses, mirroring how `include-credentials` vends credentials. The injected labels are derived from the catalog name and the server hostname, and the first column of the schema is labeled so that both object-level and field-level labels are covered. This gives other client implementations a reference server that actually returns labels to test against.

The raw HTTP client used to read the load responses requires an auth session, so requests failed with "Invalid auth session: null". The local fixture does not authenticate requests, so the empty session is used.

laskoviymishka · 2026-09-10T14:52:47Z

Close in favor of cleaned up stack - #18045

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

pvary reviewed Jul 24, 2026

View reviewed changes

Comment thread core/src/test/java/org/apache/iceberg/rest/labels/TestLabelsParser.java Outdated

pvary reviewed Jul 24, 2026

View reviewed changes

Comment thread .palantir/revapi.yml Outdated

laskoviymishka force-pushed the labels-client-impl branch from 763bffa to 5a6dc57 Compare July 24, 2026 12:07

laskoviymishka requested a review from pvary July 24, 2026 12:14

laskoviymishka marked this pull request as ready for review July 24, 2026 12:14

pvary reviewed Jul 24, 2026

View reviewed changes

Comment thread core/src/test/java/org/apache/iceberg/rest/responses/TestLoadTableResponseParser.java Outdated

pvary reviewed Jul 24, 2026

View reviewed changes

Comment thread core/src/test/java/org/apache/iceberg/rest/responses/TestLoadViewResponseParser.java Outdated

pvary reviewed Jul 24, 2026

View reviewed changes

Comment thread core/src/test/java/org/apache/iceberg/rest/responses/TestLoadTableResponse.java Outdated

laskoviymishka force-pushed the labels-client-impl branch from 5a6dc57 to 210944c Compare July 24, 2026 14:28

pvary reviewed Jul 24, 2026

View reviewed changes

Comment thread core/src/test/java/org/apache/iceberg/rest/responses/TestLoadTableResponse.java Outdated

laskoviymishka force-pushed the labels-client-impl branch from 210944c to 62a6a3f Compare July 27, 2026 08:28