feat: Add picosecond timestamp support for Json to Proto converter (#3131)

* feat: Add picosecond timestamp support for Json to Proto converter

* chore: Add edge cases for user input

* chore: Fix lint issues

* chore: Disable check for v1beta2

* chore: generate libraries at Wed Dec 10 15:59:07 UTC 2025

* chore: Address PR feedback

* chore: generate libraries at Wed Dec 10 19:01:14 UTC 2025

* chore: Fix timestamp precision check condition

---------

Co-authored-by: cloud-java-bot <[email protected]>

Author: lqiu96

google-cloud-bigquerystorage/src/main/java/com/google/cloud/bigquery/storage/v1/BQTableSchemaToProtoDescriptor.java

@@ -30,22 +30,27 @@
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
+import java.util.logging.Logger;
 
 /**
  * Converts a BQ table schema to protobuf descriptor. All field names will be converted to lowercase
  * when constructing the protobuf descriptor. The mapping between field types and field modes are
  * shown in the ImmutableMaps below.
  */
 public class BQTableSchemaToProtoDescriptor {
-  private static ImmutableMap<TableFieldSchema.Mode, FieldDescriptorProto.Label>
-      BQTableSchemaModeMap =
-          ImmutableMap.of(
-              TableFieldSchema.Mode.NULLABLE, FieldDescriptorProto.Label.LABEL_OPTIONAL,
-              TableFieldSchema.Mode.REPEATED, FieldDescriptorProto.Label.LABEL_REPEATED,
-              TableFieldSchema.Mode.REQUIRED, FieldDescriptorProto.Label.LABEL_REQUIRED);
 
-  private static ImmutableMap<TableFieldSchema.Type, FieldDescriptorProto.Type>
-      BQTableSchemaTypeMap =
+  private static final Logger LOG =
+      Logger.getLogger(BQTableSchemaToProtoDescriptor.class.getName());
+
+  private static Map<Mode, FieldDescriptorProto.Label> DEFAULT_BQ_TABLE_SCHEMA_MODE_MAP =
+      ImmutableMap.of(
+          TableFieldSchema.Mode.NULLABLE, FieldDescriptorProto.Label.LABEL_OPTIONAL,
+          TableFieldSchema.Mode.REPEATED, FieldDescriptorProto.Label.LABEL_REPEATED,
+          TableFieldSchema.Mode.REQUIRED, FieldDescriptorProto.Label.LABEL_REQUIRED);
+
+  private static Map<TableFieldSchema.Type, FieldDescriptorProto.Type>
+      DEFAULT_BQ_TABLE_SCHEMA_TYPE_MAP =
           new ImmutableMap.Builder<TableFieldSchema.Type, FieldDescriptorProto.Type>()
               .put(TableFieldSchema.Type.BOOL, FieldDescriptorProto.Type.TYPE_BOOL)
               .put(TableFieldSchema.Type.BYTES, FieldDescriptorProto.Type.TYPE_BYTES)
@@ -142,11 +147,13 @@ private static Descriptor convertBQTableSchemaToProtoDescriptorImpl(
                       .setType(BQTableField.getRangeElementType().getType())
                       .setName("start")
                       .setMode(Mode.NULLABLE)
+                      .setTimestampPrecision(BQTableField.getTimestampPrecision())
                       .build(),
                   TableFieldSchema.newBuilder()
                       .setType(BQTableField.getRangeElementType().getType())
                       .setName("end")
                       .setMode(Mode.NULLABLE)
+                      .setTimestampPrecision(BQTableField.getTimestampPrecision())
                       .build());
 
           if (dependencyMap.containsKey(rangeFields)) {
@@ -189,7 +196,7 @@ private static Descriptor convertBQTableSchemaToProtoDescriptorImpl(
    * @param index Index for protobuf fields.
    * @param scope used to name descriptors
    */
-  private static FieldDescriptorProto convertBQTableFieldToProtoField(
+  static FieldDescriptorProto convertBQTableFieldToProtoField(
       TableFieldSchema BQTableField, int index, String scope) {
     TableFieldSchema.Mode mode = BQTableField.getMode();
     String fieldName = BQTableField.getName().toLowerCase();
@@ -198,20 +205,45 @@ private static FieldDescriptorProto convertBQTableFieldToProtoField(
         FieldDescriptorProto.newBuilder()
             .setName(fieldName)
             .setNumber(index)
-            .setLabel((FieldDescriptorProto.Label) BQTableSchemaModeMap.get(mode));
+            .setLabel((FieldDescriptorProto.Label) DEFAULT_BQ_TABLE_SCHEMA_MODE_MAP.get(mode));
 
     switch (BQTableField.getType()) {
       case STRUCT:
         fieldDescriptor.setTypeName(scope);
         break;
       case RANGE:
         fieldDescriptor.setType(
-            (FieldDescriptorProto.Type) BQTableSchemaTypeMap.get(BQTableField.getType()));
+            (FieldDescriptorProto.Type)
+                DEFAULT_BQ_TABLE_SCHEMA_TYPE_MAP.get(BQTableField.getType()));
         fieldDescriptor.setTypeName(scope);
         break;
+      case TIMESTAMP:
+        // Can map to either int64 or string based on the BQ Field's timestamp precision
+        // Default: microsecond (6) maps to int64 and picosecond (12) maps to string.
+        long timestampPrecision = BQTableField.getTimestampPrecision().getValue();
+        if (timestampPrecision == 12L) {
+          fieldDescriptor.setType(
+              (FieldDescriptorProto.Type) FieldDescriptorProto.Type.TYPE_STRING);
+          break;
+        }
+        // This should never happen as this is a server response issue. If this is the case,
+        // warn the user and use INT64 as the default is microsecond precision.
+        if (timestampPrecision != 6L && timestampPrecision != 0L) {
+          LOG.warning(
+              "BigQuery Timestamp field "
+                  + BQTableField.getName()
+                  + " has timestamp precision that is not 6 or 12. Defaulting to microsecond"
+                  + " precision and mapping to INT64 protobuf type.");
+        }
+        // If the timestampPrecision value comes back as a null result from the server,
+        // timestampPrecision has a value of 0L. Use the INT64 to map to the type used
+        // for the default precision (microsecond).
+        fieldDescriptor.setType((FieldDescriptorProto.Type) FieldDescriptorProto.Type.TYPE_INT64);
+        break;
       default:
         fieldDescriptor.setType(
-            (FieldDescriptorProto.Type) BQTableSchemaTypeMap.get(BQTableField.getType()));
+            (FieldDescriptorProto.Type)
+                DEFAULT_BQ_TABLE_SCHEMA_TYPE_MAP.get(BQTableField.getType()));
         break;
     }