feat: Add high precision TIMESTAMP values for queries

src/bigquery.ts

@@ -1099,6 +1099,11 @@ export class BigQuery extends Service {
           };
         }),
       };
+    } else if ((providedType as string).toUpperCase() === 'TIMESTAMP') {
+      return {
+        type: 'TIMESTAMP',
+        timestampPrecision: '12',
+      };
     }
 
     providedType = (providedType as string).toUpperCase();
@@ -1137,7 +1142,10 @@ export class BigQuery extends Service {
     } else if (value instanceof BigQueryTime) {
       typeName = 'TIME';
     } else if (value instanceof BigQueryTimestamp) {
-      typeName = 'TIMESTAMP';
+      return {
+        type: 'TIMESTAMP', // Was typeName = 'TIMESTAMP', but now we need better timestamp precision;
+        timestampPrecision: '12',
+      };
     } else if (value instanceof Buffer) {
       typeName = 'BYTES';
     } else if (value instanceof Big) {
@@ -2249,11 +2257,30 @@ export class BigQuery extends Service {
       if (res && res.jobComplete) {
         let rows: any = [];
         if (res.schema && res.rows) {
-          rows = BigQuery.mergeSchemaWithRows_(res.schema, res.rows, {
-            wrapIntegers: options.wrapIntegers || false,
-            parseJSON: options.parseJSON,
-          });
-          delete res.rows;
+          try {
+            /*
+            Without this try/catch block, calls to getRows will hang indefinitely if
+            a call to mergeSchemaWithRows_ fails because the error never makes it to
+            the callback. Instead, pass the error to the callback the user provides
+            so that the user can see the error.
+             */
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const listParams = {
+              'formatOptions.timestampOutputFormat':
+                queryReq.formatOptions?.timestampOutputFormat,
+              'formatOptions.useInt64Timestamp':
+                queryReq.formatOptions?.useInt64Timestamp,
+            };
+            rows = BigQuery.mergeSchemaWithRows_(res.schema, res.rows, {
+              wrapIntegers: options.wrapIntegers || false,
+              parseJSON: options.parseJSON,
+              listParams,
+            });
+            delete res.rows;
+          } catch (e) {
+            (callback as SimpleQueryRowsCallback)(e as Error, null, job);
+            return;
+          }
         }
         this.trace_('[runJobsQuery] job complete');
         options._cachedRows = rows;
@@ -2334,6 +2361,18 @@ export class BigQuery extends Service {
     if (options.job) {
       return undefined;
     }
+    const hasAnyFormatOpts =
+      options['formatOptions.timestampOutputFormat'] !== undefined ||
+      options['formatOptions.useInt64Timestamp'] !== undefined;
+    const defaultOpts = hasAnyFormatOpts
+      ? {}
+      : {
+          timestampOutputFormat: 'ISO8601_STRING',
+        };
+    const formatOptions = extend(defaultOpts, {
+      timestampOutputFormat: options['formatOptions.timestampOutputFormat'],
+      useInt64Timestamp: options['formatOptions.useInt64Timestamp'],
+    });
     const req: bigquery.IQueryRequest = {
       useQueryCache: queryObj.useQueryCache,
       labels: queryObj.labels,
@@ -2342,9 +2381,7 @@ export class BigQuery extends Service {
       maximumBytesBilled: queryObj.maximumBytesBilled,
       timeoutMs: options.timeoutMs,
       location: queryObj.location || options.location,
-      formatOptions: {
-        useInt64Timestamp: true,
-      },
+      formatOptions,
       maxResults: queryObj.maxResults || options.maxResults,
       query: queryObj.query,
       useLegacySql: false,

src/job.ts

@@ -595,10 +595,21 @@ class Job extends Operation {
         let rows: any = [];
 
         if (resp.schema && resp.rows) {
-          rows = BigQuery.mergeSchemaWithRows_(resp.schema, resp.rows, {
-            wrapIntegers,
-            parseJSON,
-          });
+          try {
+            /*
+            Without this try/catch block, calls to getRows will hang indefinitely if
+            a call to mergeSchemaWithRows_ fails because the error never makes it to
+            the callback. Instead, pass the error to the callback the user provides
+            so that the user can see the error.
+             */
+            rows = BigQuery.mergeSchemaWithRows_(resp.schema, resp.rows, {
+              wrapIntegers,
+              parseJSON,
+            });
+          } catch (e) {
+            callback!(e as Error, null, null, resp);
+            return;
+          }
         }
 
         let nextQuery: QueryResultsOptions | null = null;

system-test/high-precision-query-tests.ts

@@ -0,0 +1,165 @@
+// Copyright 2026 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.
+
+import * as assert from 'assert';
+import {describe, it, before} from 'mocha';
+import {BigQuery} from '../src';
+
+describe.only('High Precision Query System Tests', () => {
+  let bigquery: BigQuery;
+  const expectedTsValueMicroseconds = '2023-01-01T12:00:00.123456000Z';
+  const expectedTsValueNanoseconds = '2023-01-01T12:00:00.123456789123Z';
+  const expectedErrorMessage =
+    'Cannot specify both timestamp_as_int and timestamp_output_format.';
+
+  before(() => {
+    bigquery = new BigQuery();
+  });
+
+  const testCases = [
+    {
+      name: 'TOF: TIMESTAMP_OUTPUT_FORMAT_UNSPECIFIED, UI64: true',
+      timestampOutputFormat: 'TIMESTAMP_OUTPUT_FORMAT_UNSPECIFIED',
+      useInt64Timestamp: true,
+      expectedTsValue: expectedTsValueMicroseconds,
+    },
+    {
+      name: 'TOF: TIMESTAMP_OUTPUT_FORMAT_UNSPECIFIED, UI64: false (default ISO8601_STRING)',
+      timestampOutputFormat: 'TIMESTAMP_OUTPUT_FORMAT_UNSPECIFIED',
+      useInt64Timestamp: false,
+      expectedTsValue: expectedTsValueMicroseconds,
+    },
+    {
+      name: 'TOF: FLOAT64, UI64: true (error)',
+      timestampOutputFormat: 'FLOAT64',
+      useInt64Timestamp: true,
+      expectedTsValue: undefined,
+      expectedError: expectedErrorMessage,
+    },
+    {
+      name: 'TOF: FLOAT64, UI64: false',
+      timestampOutputFormat: 'FLOAT64',
+      useInt64Timestamp: false,
+      expectedTsValue: expectedTsValueMicroseconds,
+    },
+    {
+      name: 'TOF: INT64, UI64: true',
+      timestampOutputFormat: 'INT64',
+      useInt64Timestamp: true,
+      expectedTsValue: expectedTsValueMicroseconds,
+    },
+    {
+      name: 'TOF: INT64, UI64: false (error)',
+      timestampOutputFormat: 'INT64',
+      useInt64Timestamp: false,
+      expectedTsValue: expectedTsValueMicroseconds,
+    },
+    {
+      name: 'TOF: ISO8601_STRING, UI64: true (error)',
+      timestampOutputFormat: 'ISO8601_STRING',
+      useInt64Timestamp: true,
+      expectedTsValue: undefined,
+      expectedError: expectedErrorMessage,
+    },
+    {
+      name: 'TOF: ISO8601_STRING, UI64: false',
+      timestampOutputFormat: 'ISO8601_STRING',
+      useInt64Timestamp: false,
+      expectedTsValue: expectedTsValueNanoseconds,
+    },
+    {
+      name: 'TOF: omitted, UI64: omitted (default INT64)',
+      timestampOutputFormat: undefined,
+      useInt64Timestamp: undefined,
+      expectedTsValue: expectedTsValueNanoseconds,
+    },
+    {
+      name: 'TOF: omitted, UI64: true',
+      timestampOutputFormat: undefined,
+      useInt64Timestamp: true,
+      expectedTsValue: expectedTsValueMicroseconds,
+    },
+    {
+      name: 'TOF: omitted, UI64: false (default ISO8601_STRING)',
+      timestampOutputFormat: undefined,
+      useInt64Timestamp: false,
+      expectedTsValue: expectedTsValueMicroseconds,
+    },
+    {
+      name: 'TOF: TIMESTAMP_OUTPUT_FORMAT_UNSPECIFIED, UI64: omitted (default INT64)',
+      timestampOutputFormat: 'TIMESTAMP_OUTPUT_FORMAT_UNSPECIFIED',
+      useInt64Timestamp: undefined,
+      expectedTsValue: expectedTsValueMicroseconds,
+    },
+    {
+      name: 'TOF: FLOAT64, UI64: omitted (error)',
+      timestampOutputFormat: 'FLOAT64',
+      useInt64Timestamp: undefined,
+      expectedTsValue: expectedTsValueMicroseconds,
+    },
+    {
+      name: 'TOF: INT64, UI64: omitted',
+      timestampOutputFormat: 'INT64',
+      useInt64Timestamp: undefined,
+      expectedTsValue: expectedTsValueMicroseconds,
+    },
+    {
+      name: 'TOF: ISO8601_STRING, UI64: omitted (error)',
+      timestampOutputFormat: 'ISO8601_STRING',
+      useInt64Timestamp: undefined,
+      expectedTsValue: expectedTsValueNanoseconds,
+    },
+  ];
+
+  testCases.forEach(testCase => {
+    it(`should handle ${testCase.name}`, async function () {
+      const query = {
+        query: 'SELECT ? as ts',
+        params: [bigquery.timestamp('2023-01-01T12:00:00.123456789123Z')],
+      };
+
+      const options: any = {};
+      if (testCase.timestampOutputFormat !== undefined) {
+        options['formatOptions.timestampOutputFormat'] =
+          testCase.timestampOutputFormat;
+      }
+      if (testCase.useInt64Timestamp !== undefined) {
+        options['formatOptions.useInt64Timestamp'] = testCase.useInt64Timestamp;
+      }
+
+      try {
+        const [rows] = await bigquery.query(query, options);
+        if (testCase.expectedError) {
+          assert.fail(
+            `Query should have failed for ${testCase.name}, but succeeded`,
+          );
+        }
+        assert.ok(rows.length > 0);
+        assert.ok(rows[0].ts.value !== undefined);
+        assert.strictEqual(rows[0].ts.value, testCase.expectedTsValue);
+      } catch (err: any) {
+        if (!testCase.expectedError) {
+          throw err;
+        }
+
+        const message = err.message;
+        assert.strictEqual(
+          message,
+          testCase.expectedError,
+          `Expected ${testCase.expectedError} error for ${testCase.name}, got ${message} (${err.message})`,
+        );
+      }
+    });
+  });
+});

test/bigquery.ts

@@ -3397,7 +3397,7 @@ describe('BigQuery', () => {
         },
         jobCreationMode: 'JOB_CREATION_REQUIRED',
         formatOptions: {
-          useInt64Timestamp: true,
+          timestampOutputFormat: 'ISO8601_STRING',
         },
       };
       assert.deepStrictEqual(req, expectedReq);
@@ -3416,7 +3416,7 @@ describe('BigQuery', () => {
         requestId: req.requestId,
         jobCreationMode: 'JOB_CREATION_OPTIONAL',
         formatOptions: {
-          useInt64Timestamp: true,
+          timestampOutputFormat: 'ISO8601_STRING',
         },
       };
       assert.deepStrictEqual(req, expectedReq);