feat: add MetadataCacheMode to ExternalTableDefinition (#3351)

* feat: add MetadataCacheMode to ExternalTableDefinition

* Update comment

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: PhongChuong

README.md

@@ -53,20 +53,20 @@ If you are using Maven without the BOM, add this to your dependencies:
 If you are using Gradle 5.x or later, add this to your dependencies:
 
 ```Groovy
-implementation platform('com.google.cloud:libraries-bom:26.40.0')
+implementation platform('com.google.cloud:libraries-bom:26.41.0')
 
 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.40.2'
+implementation 'com.google.cloud:google-cloud-bigquery:2.40.3'
 ```
 
 If you are using SBT, add this to your dependencies:
 
 ```Scala
-libraryDependencies += "com.google.cloud" % "google-cloud-bigquery" % "2.40.2"
+libraryDependencies += "com.google.cloud" % "google-cloud-bigquery" % "2.40.3"
 ```
 <!-- {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.40.2
+[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-bigquery/2.40.3
 [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/ExternalTableDefinition.java

@@ -186,6 +186,20 @@ public Builder setObjectMetadata(String objectMetadata) {
 
     abstract Builder setObjectMetadataInner(String objectMetadata);
 
+    /**
+     * [Optional] Metadata Cache Mode for the table. Set this to enable caching of metadata from
+     * external data source.
+     *
+     * @see <a
+     *     href="https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#metadatacachemode">
+     *     MetadataCacheMode</a>
+     */
+    public Builder setMetadataCacheMode(String metadataCacheMode) {
+      return setMetadataCacheModeInner(metadataCacheMode);
+    }
+
+    abstract Builder setMetadataCacheModeInner(String metadataCacheMode);
+
     /** Creates an {@code ExternalTableDefinition} object. */
     @Override
     public abstract ExternalTableDefinition build();
@@ -276,6 +290,21 @@ public String getObjectMetadata() {
   @Nullable
   abstract String getObjectMetadataInner();
 
+  /**
+   * Returns the metadata cache mode.
+   *
+   * @see <a
+   *     href="https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#metadatacachemode">
+   *     MetadataCacheMode</a>
+   */
+  @Nullable
+  public String getMetadataCacheMode() {
+    return getMetadataCacheModeInner();
+  }
+
+  @Nullable
+  abstract String getMetadataCacheModeInner();
+
   /**
    * Returns the source format, and possibly some parsing options, of the external data. Supported
    * formats are {@code CSV} and {@code NEWLINE_DELIMITED_JSON}.
@@ -387,6 +416,10 @@ com.google.api.services.bigquery.model.ExternalDataConfiguration toExternalDataC
       externalConfigurationPb.setObjectMetadata(getObjectMetadata());
     }
 
+    if (getMetadataCacheMode() != null) {
+      externalConfigurationPb.setMetadataCacheMode(getMetadataCacheMode());
+    }
+
     return externalConfigurationPb;
   }
 
@@ -580,6 +613,9 @@ static ExternalTableDefinition fromPb(Table tablePb) {
       if (externalDataConfiguration.getObjectMetadata() != null) {
         builder.setObjectMetadata(externalDataConfiguration.getObjectMetadata());
       }
+      if (externalDataConfiguration.getMetadataCacheMode() != null) {
+        builder.setMetadataCacheMode(externalDataConfiguration.getMetadataCacheMode());
+      }
     }
     return builder.build();
   }
@@ -647,6 +683,10 @@ static ExternalTableDefinition fromExternalDataConfiguration(
       builder.setObjectMetadata(externalDataConfiguration.getObjectMetadata());
     }
 
+    if (externalDataConfiguration.getMetadataCacheMode() != null) {
+      builder.setMetadataCacheMode(externalDataConfiguration.getMetadataCacheMode());
+    }
+
     return builder.build();
   }
 }

google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/ExternalTableDefinitionTest.java

@@ -59,6 +59,8 @@ public class ExternalTableDefinitionTest {
           .setSourceUriPrefix(SOURCE_URIS.get(0))
           .build();
   private static final String OBJECT_METADATA = "SIMPLE";
+
+  private static final String METADATA_CACHE_MODE = "AUTOMATIC";
   private static final ExternalTableDefinition EXTERNAL_TABLE_DEFINITION =
       ExternalTableDefinition.newBuilder(SOURCE_URIS, TABLE_SCHEMA, CSV_OPTIONS)
           .setFileSetSpecType("FILE_SET_SPEC_TYPE_FILE_SYSTEM_MATCH")
@@ -70,6 +72,7 @@ public class ExternalTableDefinitionTest {
           .setAutodetect(AUTODETECT)
           .setHivePartitioningOptions(HIVE_PARTITIONING_OPTIONS)
           .setObjectMetadata(OBJECT_METADATA)
+          .setMetadataCacheMode(METADATA_CACHE_MODE)
           .build();
 
   private static final ExternalTableDefinition EXTERNAL_TABLE_DEFINITION_AVRO =
@@ -170,5 +173,6 @@ private void compareExternalTableDefinition(
     assertEquals(expected.getAutodetect(), value.getAutodetect());
     assertEquals(expected.getHivePartitioningOptions(), value.getHivePartitioningOptions());
     assertEquals(expected.getObjectMetadata(), value.getObjectMetadata());
+    assertEquals(expected.getMetadataCacheMode(), value.getMetadataCacheMode());
   }
 }

google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/it/ITBigQueryTest.java

@@ -6832,6 +6832,32 @@ public void testExternalTableMetadataCachingNotEnable() throws InterruptedExcept
     assertTrue(remoteTable.delete());
   }
 
+  @Test
+  public void testExternalMetadataCacheModeFailForNonBiglake() {
+    // Validate that MetadataCacheMode is passed to the backend.
+    // TODO: Enhance this test after BigLake testing infrastructure is inplace.
+    String tableName = "test_metadata_cache_mode_fail_for_non_biglake";
+    TableId tableId = TableId.of(DATASET, tableName);
+    ExternalTableDefinition externalTableDefinition =
+        ExternalTableDefinition.newBuilder(
+                "gs://" + BUCKET + "/" + JSON_LOAD_FILE, TABLE_SCHEMA, FormatOptions.json())
+            .setMetadataCacheMode("AUTOMATIC")
+            .build();
+    TableInfo tableInfo = TableInfo.of(tableId, externalTableDefinition);
+
+    try {
+      bigquery.create(tableInfo);
+      fail("BigQueryException was expected");
+    } catch (BigQueryException e) {
+      BigQueryError error = e.getError();
+      assertNotNull(error);
+      assertEquals("invalid", error.getReason());
+      assertThat(
+              e.getMessage().contains("metadataCacheMode provided for non BigLake external table"))
+          .isTrue();
+    }
+  }
+
   @Test
   public void testObjectTable() throws InterruptedException {
     String tableName = "test_object_table";