Add Storage API Acceleration via Apache Arrow Deserialization

.readme-partials.yaml

@@ -104,4 +104,8 @@ introduction: |-
 
     Read more how to [use the BigQuery Storage Read API](https://cloud.google.com/bigquery/docs/reference/storage).
 
-    See sample code on the [Quickstart section](#quickstart).
+    See sample code on the [Quickstart section](#quickstart).
+
+    ### Apache Arrow Picosecond Precision Limitation
+    Please note that the Apache Arrow JavaScript library currently does not support picosecond precision (`Timestamp[ps]`) logical types.
+    When using the Storage Read API with Arrow format, if picosecond precision is requested, the Node.js client library will automatically fall back to microsecond precision and log a warning to prevent deserialization errors.

protos/google/cloud/bigquery/storage/v1/arrow.proto

@@ -58,7 +58,25 @@ message ArrowSerializationOptions {
     ZSTD = 2;
   }
 
+  // Precision of the TIMESTAMP type.
+  enum PicosecondTimestampPrecision {
+    // If unspecified, microsecond precision will be used.
+    PICOSECOND_TIMESTAMP_PRECISION_UNSPECIFIED = 0;
+
+    // Use microsecond precision.
+    MICROSECOND = 1;
+
+    // Use nanosecond precision.
+    NANOSECOND = 2;
+
+    // Use picosecond precision.
+    PICOSECOND = 3;
+  }
+
   // The compression codec to use for Arrow buffers in serialized record
   // batches.
   CompressionCodec buffer_compression = 2;
+
+  // The precision of the TIMESTAMP type.
+  PicosecondTimestampPrecision timestamp_precision = 3;
 }

src/v1/big_query_read_client.ts

@@ -542,6 +542,26 @@
       this._gaxModule.routingHeader.fromParams({
         'read_session.table': request.readSession!.table ?? '',
       });
+
+    // Apache Arrow does not currently support picosecond precision in JavaScript.
+    // If picosecond precision is requested, we fall back to microsecond precision
+    // to avoid deserialization errors.
+    const timestampPrecision =
+      request.readSession?.readOptions?.arrowSerializationOptions
+        ?.timestampPrecision;
+    if (
+      timestampPrecision ===
+        protos.google.cloud.bigquery.storage.v1.ArrowSerializationOptions
+          .PicosecondTimestampPrecision.PICOSECOND ||
+      timestampPrecision === 'PICOSECOND'
+    ) {
+      console.warn(
+        'Apache Arrow does not support picosecond precision. Falling back to microsecond precision.'
+      );
+      request.readSession!.readOptions!.arrowSerializationOptions!.timestampPrecision =
+        protos.google.cloud.bigquery.storage.v1.ArrowSerializationOptions.PicosecondTimestampPrecision.MICROSECOND;
+    }
+
     this.initialize().catch(err => {
       throw err;
     });
@@ -575,7 +595,7 @@
           return [response, options, rawResponse];
         },
       )
       .catch((error: any) => {
         if (
           error &&
           'statusDetails' in error &&
@@ -737,7 +757,7 @@
           return [response, options, rawResponse];
         },
       )
       .catch((error: any) => {
         if (
           error &&
           'statusDetails' in error &&