feat: Add timestamp_precision to Field (#4014)

* feat: Add timestamp_precision to Field

* Apply suggestion from @gemini-code-assist[bot]

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* chore: Address GCA PR feedback

* chore: Fix typo

* chore: Remove default value

* chore: Address PR feedback

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: lqiu96

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

@@ -25,6 +25,7 @@
 import com.google.api.services.bigquery.model.TableFieldSchema;
 import com.google.common.base.Function;
 import com.google.common.base.MoreObjects;
+import com.google.common.base.Preconditions;
 import com.google.common.collect.Lists;
 import java.io.Serializable;
 import java.util.List;
@@ -62,6 +63,7 @@ public TableFieldSchema apply(Field field) {
   private final Long maxLength;
   private final Long scale;
   private final Long precision;
+  private final Long timestampPrecision;
   private final String defaultValueExpression;
   private final String collation;
   private final FieldElementType rangeElementType;
@@ -88,6 +90,7 @@ public static final class Builder {
     private Long maxLength;
     private Long scale;
     private Long precision;
+    private Long timestampPrecision;
     private String defaultValueExpression;
     private String collation;
     private FieldElementType rangeElementType;
@@ -104,6 +107,7 @@ private Builder(Field field) {
       this.maxLength = field.maxLength;
       this.scale = field.scale;
       this.precision = field.precision;
+      this.timestampPrecision = field.timestampPrecision;
       this.defaultValueExpression = field.defaultValueExpression;
       this.collation = field.collation;
       this.rangeElementType = field.rangeElementType;
@@ -254,6 +258,19 @@ public Builder setPrecision(Long precision) {
       return this;
     }
 
+    /**
+     * Specifies the precision for TIMESTAMP types.
+     *
+     * <p>The default value is 6. Possible values are 6 (microsecond) or 12 (picosecond).
+     */
+    public Builder setTimestampPrecision(Long timestampPrecision) {
+      Preconditions.checkArgument(
+          timestampPrecision == 6L || timestampPrecision == 12L,
+          "Timestamp Precision must be 6 (microsecond) or 12 (picosecond)");
+      this.timestampPrecision = timestampPrecision;
+      return this;
+    }
+
     /**
      * DefaultValueExpression is used to specify the default value of a field using a SQL
      * expression. It can only be set for top level fields (columns).
@@ -317,6 +334,7 @@ private Field(Builder builder) {
     this.maxLength = builder.maxLength;
     this.scale = builder.scale;
     this.precision = builder.precision;
+    this.timestampPrecision = builder.timestampPrecision;
     this.defaultValueExpression = builder.defaultValueExpression;
     this.collation = builder.collation;
     this.rangeElementType = builder.rangeElementType;
@@ -370,6 +388,11 @@ public Long getPrecision() {
     return precision;
   }
 
+  /** Returns the precision for TIMESTAMP type. */
+  public Long getTimestampPrecision() {
+    return timestampPrecision;
+  }
+
   /** Return the default value of the field. */
   public String getDefaultValueExpression() {
     return defaultValueExpression;
@@ -408,6 +431,7 @@ public String toString() {
         .add("maxLength", maxLength)
         .add("scale", scale)
         .add("precision", precision)
+        .add("timestampPrecision", timestampPrecision)
         .add("defaultValueExpression", defaultValueExpression)
         .add("collation", collation)
         .add("rangeElementType", rangeElementType)
@@ -416,7 +440,19 @@ public String toString() {
 
   @Override
   public int hashCode() {
-    return Objects.hash(name, type, mode, description, policyTags, rangeElementType);
+    return Objects.hash(
+        name,
+        type,
+        mode,
+        description,
+        policyTags,
+        maxLength,
+        scale,
+        precision,
+        timestampPrecision,
+        defaultValueExpression,
+        collation,
+        rangeElementType);
   }
 
   @Override
@@ -490,6 +526,9 @@ TableFieldSchema toPb() {
     if (precision != null) {
       fieldSchemaPb.setPrecision(precision);
     }
+    if (timestampPrecision != null) {
+      fieldSchemaPb.setTimestampPrecision(timestampPrecision);
+    }
     if (defaultValueExpression != null) {
       fieldSchemaPb.setDefaultValueExpression(defaultValueExpression);
     }
@@ -527,6 +566,9 @@ static Field fromPb(TableFieldSchema fieldSchemaPb) {
     if (fieldSchemaPb.getPrecision() != null) {
       fieldBuilder.setPrecision(fieldSchemaPb.getPrecision());
     }
+    if (fieldSchemaPb.getTimestampPrecision() != null) {
+      fieldBuilder.setTimestampPrecision(fieldSchemaPb.getTimestampPrecision());
+    }
     if (fieldSchemaPb.getDefaultValueExpression() != null) {
       fieldBuilder.setDefaultValueExpression(fieldSchemaPb.getDefaultValueExpression());
     }

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

@@ -17,6 +17,7 @@
 package com.google.cloud.bigquery;
 
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertThrows;
 
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
@@ -213,6 +214,20 @@ public void testSubFieldWithClonedType() throws Exception {
     Field.of("field", clonedRecord, Field.of("subfield", LegacySQLTypeName.BOOLEAN));
   }
 
+  @Test
+  public void setTimestampPrecisionValues() {
+    Field.Builder builder = Field.newBuilder(FIELD_NAME1, FIELD_TYPE1);
+
+    // Value values: 6L or 12L
+    builder.setTimestampPrecision(6L);
+    builder.setTimestampPrecision(12L);
+
+    assertThrows(IllegalArgumentException.class, () -> builder.setTimestampPrecision(-1L));
+    assertThrows(IllegalArgumentException.class, () -> builder.setTimestampPrecision(0L));
+    assertThrows(IllegalArgumentException.class, () -> builder.setTimestampPrecision(5L));
+    assertThrows(IllegalArgumentException.class, () -> builder.setTimestampPrecision(13L));
+  }
+
   private void compareFieldSchemas(Field expected, Field value) {
     assertEquals(expected, value);
     assertEquals(expected.getName(), value.getName());