feat: add MetadataCacheStatistics to Job QueryStatistics

README.md

@@ -60,13 +60,13 @@ implementation 'com.google.cloud:google-cloud-bigquery'
 If you are using Gradle without BOM, add this to your dependencies:
 
 ```Groovy
-implementation 'com.google.cloud:google-cloud-bigquery:2.37.0'
+implementation 'com.google.cloud:google-cloud-bigquery:2.37.1'
 ```
 
 If you are using SBT, add this to your dependencies:
 
 ```Scala
-libraryDependencies += "com.google.cloud" % "google-cloud-bigquery" % "2.37.0"
+libraryDependencies += "com.google.cloud" % "google-cloud-bigquery" % "2.37.1"
 ```
 <!-- {x-version-update-end} -->
 
@@ -351,7 +351,7 @@ Java is a registered trademark of Oracle and/or its affiliates.
 [kokoro-badge-link-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-bigquery/java11.html
 [stability-image]: https://img.shields.io/badge/stability-stable-green
 [maven-version-image]: https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-bigquery.svg
-[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-bigquery/2.37.0
+[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-bigquery/2.37.1
 [authentication]: https://github.com/googleapis/google-cloud-java#authentication
 [auth-scopes]: https://developers.google.com/identity/protocols/oauth2/scopes
 [predefined-iam-roles]: https://cloud.google.com/iam/docs/understanding-roles#predefined_roles

google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/JobStatistics.java

@@ -358,6 +358,7 @@ public static class QueryStatistics extends JobStatistics {
     private final List<TimelineSample> timeline;
     private final Schema schema;
     private final SearchStats searchStats;
+    private final MetadataCacheStats metadataCacheStats;
     private final List<QueryParameter> queryParameters;
 
     /**
@@ -444,6 +445,8 @@ static final class Builder extends JobStatistics.Builder<QueryStatistics, Builde
       private List<QueryParameter> queryParameters;
       private SearchStats searchStats;
 
+      private MetadataCacheStats metadataCacheStats;
+
       private Builder() {}
 
       private Builder(com.google.api.services.bigquery.model.JobStatistics statisticsPb) {
@@ -493,6 +496,10 @@ private Builder(com.google.api.services.bigquery.model.JobStatistics statisticsP
           if (statisticsPb.getQuery().getSearchStatistics() != null) {
             this.searchStats = SearchStats.fromPb(statisticsPb.getQuery().getSearchStatistics());
           }
+          if (statisticsPb.getQuery().getMetadataCacheStatistics() != null) {
+            this.metadataCacheStats =
+                MetadataCacheStats.fromPb(statisticsPb.getQuery().getMetadataCacheStatistics());
+          }
           if (statisticsPb.getQuery().getDmlStats() != null) {
             this.dmlStats = DmlStats.fromPb(statisticsPb.getQuery().getDmlStats());
           }
@@ -599,6 +606,11 @@ Builder setSearchStats(SearchStats searchStats) {
         return self();
       }
 
+      Builder setMetadataCacheStats(MetadataCacheStats metadataCacheStats) {
+        this.metadataCacheStats = metadataCacheStats;
+        return self();
+      }
+
       Builder setQueryParameters(List<QueryParameter> queryParameters) {
         this.queryParameters = queryParameters;
         return self();
@@ -631,6 +643,7 @@ private QueryStatistics(Builder builder) {
       this.timeline = builder.timeline;
       this.schema = builder.schema;
       this.searchStats = builder.searchStats;
+      this.metadataCacheStats = builder.metadataCacheStats;
       this.queryParameters = builder.queryParameters;
     }
 
@@ -761,6 +774,11 @@ public SearchStats getSearchStats() {
       return searchStats;
     }
 
+    /** Statistics for metadata caching in BigLake tables. */
+    public MetadataCacheStats getMetadataCacheStats() {
+      return metadataCacheStats;
+    }
+
     /**
      * Standard SQL only: Returns a list of undeclared query parameters detected during a dry run
      * validation.
@@ -781,6 +799,7 @@ ToStringHelper toStringHelper() {
           .add("timeline", timeline)
           .add("schema", schema)
           .add("searchStats", searchStats)
+          .add("metadataCacheStats", metadataCacheStats)
           .add("queryParameters", queryParameters);
     }
 
@@ -804,6 +823,7 @@ public final int hashCode() {
           queryPlan,
           schema,
           searchStats,
+          metadataCacheStats,
           queryParameters);
     }
 
@@ -849,6 +869,9 @@ com.google.api.services.bigquery.model.JobStatistics toPb() {
       if (searchStats != null) {
         queryStatisticsPb.setSearchStatistics(searchStats.toPb());
       }
+      if (metadataCacheStats != null) {
+        queryStatisticsPb.setMetadataCacheStatistics(metadataCacheStats.toPb());
+      }
       if (queryParameters != null) {
         queryStatisticsPb.setUndeclaredQueryParameters(queryParameters);
       }

google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/MetadataCacheStats.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed 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 com.google.cloud.bigquery;
+
+import com.google.api.services.bigquery.model.MetadataCacheStatistics;
+import com.google.auto.value.AutoValue;
+import java.io.Serializable;
+import java.util.List;
+import java.util.stream.Collectors;
+import javax.annotation.Nullable;
+
+/** Represents statistics for metadata caching in BigLake tables. */
+@AutoValue
+public abstract class MetadataCacheStats implements Serializable {
+
+  private static final long serialVersionUID = 1L;
+
+  @AutoValue.Builder
+  public abstract static class Builder {
+    /** Sets the free form human-readable reason metadata caching was unused for the job. */
+    public abstract MetadataCacheStats.Builder setTableMetadataCacheUsage(
+        List<TableMetadataCacheUsage> tableMetadataCacheUsage);
+
+    /** Creates a @code MetadataCacheStats} object. */
+    public abstract MetadataCacheStats build();
+  }
+
+  public abstract Builder toBuilder();
+
+  public static Builder newBuilder() {
+    return new AutoValue_MetadataCacheStats.Builder();
+  }
+
+  @Nullable
+  public abstract List<TableMetadataCacheUsage> getTableMetadataCacheUsage();
+
+  MetadataCacheStatistics toPb() {
+    MetadataCacheStatistics metadataCacheStatistics = new MetadataCacheStatistics();
+    if (getTableMetadataCacheUsage() != null) {
+      metadataCacheStatistics.setTableMetadataCacheUsage(
+          getTableMetadataCacheUsage().stream()
+              .map(TableMetadataCacheUsage::toPb)
+              .collect(Collectors.toList()));
+    }
+    return metadataCacheStatistics;
+  }
+
+  static MetadataCacheStats fromPb(MetadataCacheStatistics metadataCacheStatistics) {
+    Builder builder = newBuilder();
+    if (metadataCacheStatistics.getTableMetadataCacheUsage() != null) {
+      builder.setTableMetadataCacheUsage(
+          metadataCacheStatistics.getTableMetadataCacheUsage().stream()
+              .map(TableMetadataCacheUsage::fromPb)
+              .collect(Collectors.toList()));
+    }
+    return builder.build();
+  }
+}

google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/TableMetadataCacheUsage.java

@@ -0,0 +1,118 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed 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 com.google.cloud.bigquery;
+
+import com.google.auto.value.AutoValue;
+import java.io.Serializable;
+import javax.annotation.Nullable;
+
+/** Represents Table level detail on the usage of metadata caching. */
+@AutoValue
+public abstract class TableMetadataCacheUsage implements Serializable {
+
+  private static final long serialVersionUID = 1L;
+
+  /** Reason for not using metadata caching for the table. */
+  public enum UnusedReason {
+    /** Unused reasons not specified. */
+    UNUSED_REASON_UNSPECIFIED,
+
+    /** Metadata cache was outside the table's maxStaleness. */
+    EXCEEDED_MAX_STALENESS,
+
+    /**
+     * Metadata caching feature is not enabled. Update BigLake tables to enable the metadata
+     * caching.
+     */
+    METADATA_CACHING_NOT_ENABLED,
+
+    /** Other unknown reason. */
+    OTHER_REASON
+  }
+
+  @AutoValue.Builder
+  public abstract static class Builder {
+    /** Sets the free form human-readable reason metadata caching was unused for the job. */
+    public abstract TableMetadataCacheUsage.Builder setExplanation(String explanation);
+
+    /** Sets the metadata caching eligible table referenced in the query. */
+    public abstract TableMetadataCacheUsage.Builder setTableReference(TableId tableReference);
+
+    /** Sets the table type. */
+    public abstract TableMetadataCacheUsage.Builder setTableType(String tableType);
+
+    /** Sets reason for not using metadata caching for the table. */
+    public abstract TableMetadataCacheUsage.Builder setUnusedReason(UnusedReason unusedReason);
+
+    /** Creates a @code TableMetadataCacheUsage} object. */
+    public abstract TableMetadataCacheUsage build();
+  }
+
+  public abstract Builder toBuilder();
+
+  public static Builder newBuilder() {
+    return new AutoValue_TableMetadataCacheUsage.Builder();
+  }
+
+  @Nullable
+  public abstract String getExplanation();
+
+  @Nullable
+  public abstract TableId getTableReference();
+
+  @Nullable
+  public abstract String getTableType();
+
+  @Nullable
+  public abstract UnusedReason getUnusedReason();
+
+  com.google.api.services.bigquery.model.TableMetadataCacheUsage toPb() {
+    com.google.api.services.bigquery.model.TableMetadataCacheUsage tableMetadataCacheUsage =
+        new com.google.api.services.bigquery.model.TableMetadataCacheUsage();
+    if (getExplanation() != null) {
+      tableMetadataCacheUsage.setExplanation(getExplanation());
+    }
+    if (getTableReference() != null) {
+      tableMetadataCacheUsage.setTableReference(getTableReference().toPb());
+    }
+    if (getTableType() != null) {
+      tableMetadataCacheUsage.setTableType(getTableType());
+    }
+    if (getUnusedReason() != null) {
+      tableMetadataCacheUsage.setUnusedReason(getUnusedReason().toString());
+    }
+    return tableMetadataCacheUsage;
+  }
+
+  static TableMetadataCacheUsage fromPb(
+      com.google.api.services.bigquery.model.TableMetadataCacheUsage tableMetadataCacheUsage) {
+    Builder builder = newBuilder();
+    if (tableMetadataCacheUsage.getExplanation() != null) {
+      builder.setExplanation(tableMetadataCacheUsage.getExplanation());
+    }
+    if (tableMetadataCacheUsage.getTableReference() != null) {
+      builder.setTableReference(TableId.fromPb(tableMetadataCacheUsage.getTableReference()));
+    }
+    if (tableMetadataCacheUsage.getTableType() != null) {
+      builder.setTableType(tableMetadataCacheUsage.getTableType());
+    }
+    if (tableMetadataCacheUsage.getUnusedReason() != null) {
+      builder.setUnusedReason(UnusedReason.valueOf(tableMetadataCacheUsage.getUnusedReason()));
+    }
+    return builder.build();
+  }
+}

google-cloud-bigquery/src/test/java/MetadataCacheStatsTest.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed 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 com.google.cloud.bigquery;
+
+import static org.junit.Assert.assertEquals;
+
+import com.google.api.services.bigquery.model.MetadataCacheStatistics;
+import com.google.common.collect.ImmutableList;
+import com.google.common.truth.Truth;
+import java.util.List;
+import java.util.stream.Collectors;
+import org.junit.Test;
+
+public class MetadataCacheStatsTest {
+  private static List<com.google.api.services.bigquery.model.TableMetadataCacheUsage>
+      TABLE_METADATA_CACHE_USAGE_PB_LIST =
+          ImmutableList.of(
+              new com.google.api.services.bigquery.model.TableMetadataCacheUsage()
+                  .setExplanation("test explanation"));
+
+  private static final MetadataCacheStats METADATA_CACHE_STATS =
+      MetadataCacheStats.newBuilder()
+          .setTableMetadataCacheUsage(
+              TABLE_METADATA_CACHE_USAGE_PB_LIST.stream()
+                  .map(TableMetadataCacheUsage::fromPb)
+                  .collect(Collectors.toList()))
+          .build();
+
+  private static final MetadataCacheStatistics METADATA_CACHE_STATISTICS_PB =
+      new MetadataCacheStatistics().setTableMetadataCacheUsage(TABLE_METADATA_CACHE_USAGE_PB_LIST);
+
+  @Test
+  public void testToPbAndFromPb() {
+    assertEquals(METADATA_CACHE_STATISTICS_PB, METADATA_CACHE_STATS.toPb());
+    compareMetadataCacheStats(
+        METADATA_CACHE_STATS, MetadataCacheStats.fromPb(METADATA_CACHE_STATISTICS_PB));
+  }
+
+  private void compareMetadataCacheStats(MetadataCacheStats expected, MetadataCacheStats value) {
+    assertEquals(expected, value);
+    assertEquals(expected.hashCode(), value.hashCode());
+    assertEquals(expected.toString(), value.toString());
+    Truth.assertThat(
+        expected.getTableMetadataCacheUsage().containsAll(value.getTableMetadataCacheUsage()));
+  }
+}