Catalog Labels: client-library read support for C++ #938

One of the tasks from apache/iceberg#18126

Below are relevant sections quoted as is, as written by @laskoviymishka from apache/iceberg#18126

Summary

Catalog Labels were added to the Iceberg REST spec in #15750 (merged) and implemented on the Java client/engine side as a stacked set of PRs (#18045–#18049). This is a tracking issue to bring the other REST client libraries to iceberg-cpp** — to read-path parity.

Labels are catalog-provided enrichment, not table state: they are returned on the load response, are transient/runtime-only, and are never persisted into table metadata or serialized. A client that ignores labels remains spec-compliant.

Wire shape

LoadTableResult / LoadViewResult gain an optional labels object:

"labels": {
  "object-labels": { "<key>": "<value>" },
  "fields": [ { "field-id": 3, "labels": { "classification": "pii" } } ]
}

• object-labels: flat catalog-object-level map. fields: per-field labels keyed by field-id.
• A field-id may carry multiple keys and may not resolve to a current column (e.g. a dropped column) — clients should tolerate both.

Java reference implementation

• Spec: #15750
• serde: #18045 · table accessor (SupportsLabels): #18046 · REST server test fixture: #18047 · labels metadata table: #18048 · Spark DESCRIBE: #18049

Shared prerequisite

Client integration tests need a server that emits labels — that is the REST server test fixture (#18047); once merged it must ship in the iceberg-rest-fixture Docker image. This gates the integration-test PRs only; unit-test PRs (mocked responses) can proceed immediately.

• #18047 merged and published to the iceberg-rest-fixture image

Per-repo proposed PRs

Each repo mirrors the Java layering (serde → table accessor → labels metadata table → integration tests), modeled on that client's existing storage-credentials / vended-credentials field. Read-path parity (metadata table) is included in all four. Rust and C++ are table-only (no LoadViewResult yet). Each per-repo group is a stack (each PR based on the previous); repos are independent.

iceberg-cpp — table-only (no views yet)

• C1 serde (FieldLabels/CatalogLabels + LoadTableResult.labels) + Table::catalog_labels() accessor + first REST serde unit test
• C2 labels kind on inspect::MetadataTable
• C3 integration tests against the fixture (gated)

Notes

• C++ is table-only until LoadViewResult lands in those clients.