Core: add labels to the load table/view read path

core/src/main/java/org/apache/iceberg/FieldLabel.java

@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.iceberg;
+
+import java.util.Map;
+import org.immutables.value.Value;
+
+/** Labels attached to a single field, identified by its field id. See {@link Labels}. */
+@Value.Immutable
+public interface FieldLabel {
+  int fieldId();
+
+  Map<String, String> labels();
+}

core/src/main/java/org/apache/iceberg/FieldLabelParser.java

@@ -0,0 +1,64 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.iceberg;
+
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.databind.JsonNode;
+import java.io.IOException;
+import org.apache.iceberg.relocated.com.google.common.base.Preconditions;
+import org.apache.iceberg.util.JsonUtil;
+
+public class FieldLabelParser {
+  private static final String FIELD_ID = "field-id";
+  private static final String LABELS = "labels";
+
+  private FieldLabelParser() {}
+
+  public static String toJson(FieldLabel fieldLabel) {
+    return toJson(fieldLabel, false);
+  }
+
+  public static String toJson(FieldLabel fieldLabel, boolean pretty) {
+    return JsonUtil.generate(gen -> toJson(fieldLabel, gen), pretty);
+  }
+
+  public static void toJson(FieldLabel fieldLabel, JsonGenerator gen) throws IOException {
+    Preconditions.checkArgument(null != fieldLabel, "Invalid field labels: null");
+
+    gen.writeStartObject();
+
+    gen.writeNumberField(FIELD_ID, fieldLabel.fieldId());
+    JsonUtil.writeStringMap(LABELS, fieldLabel.labels(), gen);
+
+    gen.writeEndObject();
+  }
+
+  public static FieldLabel fromJson(String json) {
+    return JsonUtil.parse(json, FieldLabelParser::fromJson);
+  }
+
+  public static FieldLabel fromJson(JsonNode json) {
+    Preconditions.checkArgument(null != json, "Cannot parse field labels from null object");
+
+    return ImmutableFieldLabel.builder()
+        .fieldId(JsonUtil.getInt(FIELD_ID, json))
+        .labels(JsonUtil.getStringMap(LABELS, json))
+        .build();
+  }
+}

core/src/main/java/org/apache/iceberg/Labels.java

@@ -0,0 +1,41 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.iceberg;
+
+import java.util.List;
+import java.util.Map;
+import org.immutables.value.Value;
+
+/** Optional catalog-provided labels returned on a load response. */
+@Value.Immutable
+public interface Labels {
+  Labels EMPTY = ImmutableLabels.builder().build();
+
+  /** Object-level labels. */
+  Map<String, String> objectLabels();
+
+  /** Field-level labels */
+  List<FieldLabel> fields();
+
+  /** Returns true when there are neither object-level nor field-level labels. */
+  @Value.Derived
+  default boolean isEmpty() {
+    return objectLabels().isEmpty() && fields().isEmpty();
+  }
+}

core/src/main/java/org/apache/iceberg/LabelsParser.java

@@ -0,0 +1,81 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.iceberg;
+
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.databind.JsonNode;
+import java.io.IOException;
+import org.apache.iceberg.relocated.com.google.common.base.Preconditions;
+import org.apache.iceberg.util.JsonUtil;
+
+public class LabelsParser {
+  private static final String OBJECT_LABELS = "object-labels";
+  private static final String FIELDS = "fields";
+
+  private LabelsParser() {}
+
+  public static String toJson(Labels labels) {
+    return toJson(labels, false);
+  }
+
+  public static String toJson(Labels labels, boolean pretty) {
+    return JsonUtil.generate(gen -> toJson(labels, gen), pretty);
+  }
+
+  public static void toJson(Labels labels, JsonGenerator gen) throws IOException {
+    Preconditions.checkArgument(null != labels, "Invalid labels: null");
+
+    gen.writeStartObject();
+
+    if (!labels.objectLabels().isEmpty()) {
+      JsonUtil.writeStringMap(OBJECT_LABELS, labels.objectLabels(), gen);
+    }
+
+    if (!labels.fields().isEmpty()) {
+      gen.writeArrayFieldStart(FIELDS);
+      for (FieldLabel fieldLabel : labels.fields()) {
+        FieldLabelParser.toJson(fieldLabel, gen);
+      }
+
+      gen.writeEndArray();
+    }
+
+    gen.writeEndObject();
+  }
+
+  public static Labels fromJson(String json) {
+    return JsonUtil.parse(json, LabelsParser::fromJson);
+  }
+
+  public static Labels fromJson(JsonNode json) {
+    Preconditions.checkArgument(null != json, "Cannot parse labels from null object");
+
+    ImmutableLabels.Builder builder = ImmutableLabels.builder();
+
+    if (json.hasNonNull(OBJECT_LABELS)) {
+      builder.objectLabels(JsonUtil.getStringMap(OBJECT_LABELS, json));
+    }
+
+    if (json.hasNonNull(FIELDS)) {
+      builder.fields(JsonUtil.getObjectList(FIELDS, json, FieldLabelParser::fromJson));
+    }
+
+    return builder.build();
+  }
+}

core/src/main/java/org/apache/iceberg/rest/responses/LoadTableResponse.java

@@ -20,6 +20,7 @@
 
 import java.util.List;
 import java.util.Map;
+import org.apache.iceberg.Labels;
 import org.apache.iceberg.TableMetadata;
 import org.apache.iceberg.relocated.com.google.common.base.MoreObjects;
 import org.apache.iceberg.relocated.com.google.common.base.Preconditions;
@@ -47,6 +48,7 @@ public class LoadTableResponse implements RESTResponse {
   private TableMetadata metadataWithLocation;
   private List<Credential> credentials;
   private RemoteSigningConfig remoteSigningConfig;
+  private Labels labels;
 
   public LoadTableResponse() {
     // Required for Jackson deserialization
@@ -57,12 +59,14 @@ private LoadTableResponse(
       TableMetadata metadata,
       Map<String, String> config,
       List<Credential> credentials,
-      RemoteSigningConfig remoteSigningConfig) {
+      RemoteSigningConfig remoteSigningConfig,
+      Labels labels) {
     this.metadataLocation = metadataLocation;
     this.metadata = metadata;
     this.config = config;
     this.credentials = credentials;
     this.remoteSigningConfig = remoteSigningConfig;
+    this.labels = labels;
   }
 
   @Override
@@ -95,12 +99,17 @@ public RemoteSigningConfig remoteSigningConfig() {
     return remoteSigningConfig != null ? remoteSigningConfig : RemoteSigningConfig.EMPTY;
   }
 
+  public Labels labels() {
+    return labels != null ? labels : Labels.EMPTY;
+  }
+
   @Override
   public String toString() {
     return MoreObjects.toStringHelper(this)
         .add("metadataLocation", metadataLocation)
         .add("metadata", metadata)
         .add("config", config)
+        .add("labels", labels)
         .toString();
   }
 
@@ -114,6 +123,7 @@ public static class Builder {
     private final Map<String, String> config = Maps.newHashMap();
     private final List<Credential> credentials = Lists.newArrayList();
     private RemoteSigningConfig remoteSigningConfig = RemoteSigningConfig.EMPTY;
+    private Labels labels = Labels.EMPTY;
 
     private Builder() {}
 
@@ -148,10 +158,15 @@ public Builder withRemoteSigningConfig(RemoteSigningConfig signingConfig) {
       return this;
     }
 
+    public Builder withLabels(Labels tableLabels) {
+      this.labels = tableLabels;
+      return this;
+    }
+
     public LoadTableResponse build() {
       Preconditions.checkNotNull(metadata, "Invalid metadata: null");
       return new LoadTableResponse(
-          metadataLocation, metadata, config, credentials, remoteSigningConfig);
+          metadataLocation, metadata, config, credentials, remoteSigningConfig, labels);
     }
   }
 }

core/src/main/java/org/apache/iceberg/rest/responses/LoadTableResponseParser.java

@@ -21,6 +21,7 @@
 import com.fasterxml.jackson.core.JsonGenerator;
 import com.fasterxml.jackson.databind.JsonNode;
 import java.io.IOException;
+import org.apache.iceberg.LabelsParser;
 import org.apache.iceberg.TableMetadata;
 import org.apache.iceberg.TableMetadataParser;
 import org.apache.iceberg.relocated.com.google.common.base.Preconditions;
@@ -36,6 +37,7 @@ public class LoadTableResponseParser {
   private static final String CONFIG = "config";
   private static final String STORAGE_CREDENTIALS = "storage-credentials";
   private static final String REMOTE_SIGNING_CONFIG = "remote-signing-config";
+  private static final String LABELS = "labels";
 
   private LoadTableResponseParser() {}
 
@@ -77,6 +79,11 @@ public static void toJson(LoadTableResponse response, JsonGenerator gen) throws
       RemoteSigningConfigParser.toJson(response.remoteSigningConfig(), gen);
     }
 
+    if (!response.labels().isEmpty()) {
+      gen.writeFieldName(LABELS);
+      LabelsParser.toJson(response.labels(), gen);
+    }
+
     gen.writeEndObject();
   }
 
@@ -113,6 +120,10 @@ public static LoadTableResponse fromJson(JsonNode json) {
           RemoteSigningConfigParser.fromJson(JsonUtil.get(REMOTE_SIGNING_CONFIG, json)));
     }
 
+    if (json.hasNonNull(LABELS)) {
+      builder.withLabels(LabelsParser.fromJson(JsonUtil.get(LABELS, json)));
+    }
+
     return builder.build();
   }
 }

core/src/main/java/org/apache/iceberg/rest/responses/LoadViewResponse.java

@@ -19,6 +19,7 @@
 package org.apache.iceberg.rest.responses;
 
 import java.util.Map;
+import org.apache.iceberg.Labels;
 import org.apache.iceberg.rest.RESTResponse;
 import org.apache.iceberg.view.ViewMetadata;
 import org.immutables.value.Value;
@@ -31,6 +32,11 @@ public interface LoadViewResponse extends RESTResponse {
 
   Map<String, String> config();
 
+  @Value.Default
+  default Labels labels() {
+    return Labels.EMPTY;
+  }
+
   @Override
   default void validate() {
     // nothing to validate as it's not possible to create an invalid instance

core/src/main/java/org/apache/iceberg/rest/responses/LoadViewResponseParser.java

@@ -21,6 +21,7 @@
 import com.fasterxml.jackson.core.JsonGenerator;
 import com.fasterxml.jackson.databind.JsonNode;
 import java.io.IOException;
+import org.apache.iceberg.LabelsParser;
 import org.apache.iceberg.relocated.com.google.common.base.Preconditions;
 import org.apache.iceberg.util.JsonUtil;
 import org.apache.iceberg.view.ViewMetadata;
@@ -31,6 +32,7 @@ public class LoadViewResponseParser {
   private static final String METADATA_LOCATION = "metadata-location";
   private static final String METADATA = "metadata";
   private static final String CONFIG = "config";
+  private static final String LABELS = "labels";
 
   private LoadViewResponseParser() {}
 
@@ -56,6 +58,11 @@ public static void toJson(LoadViewResponse response, JsonGenerator gen) throws I
       JsonUtil.writeStringMap(CONFIG, response.config(), gen);
     }
 
+    if (!response.labels().isEmpty()) {
+      gen.writeFieldName(LABELS);
+      LabelsParser.toJson(response.labels(), gen);
+    }
+
     gen.writeEndObject();
   }
 
@@ -80,6 +87,10 @@ public static LoadViewResponse fromJson(JsonNode json) {
       builder.config(JsonUtil.getStringMap(CONFIG, json));
     }
 
+    if (json.hasNonNull(LABELS)) {
+      builder.labels(LabelsParser.fromJson(JsonUtil.get(LABELS, json)));
+    }
+
     return builder.build();
   }
 }