feat: Add high precision TIMESTAMP values for queries by danieljbruce · Pull Request #7147 · googleapis/google-cloud-node

danieljbruce · 2026-02-05T16:19:43Z

Description

This PR makes it so that all requests to the /queries endpoint support returning high precision results for the TIMESTAMP type. This ensures that users will always get the highest precision possible for TIMESTAMP typed values requested in queries provided they request getting a higher precision timestamp by specifying a type of TIMESTAMP(12):

const query = {
    query: 'SELECT ? as ts',
    params: [bigquery.timestamp('2023-01-01T12:00:00.123456789123Z')],
    types: ['TIMESTAMP(12)']
};
const [rows] = await bigquery.query(query, options);

googleapis/nodejs-bigquery#1596 adds similar support for the /data REST endpoint which may be useful for reference. And googleapis/java-bigquery#4010 contains a similar PR to this one, but for the Bigquery Java codebase.

Impact

Allows users to opt in to fetching high precision timestamps for calls to the /queries endpoint.

Testing

System tests were added to make sure no matter what formatOptions they provide, the values sent back by the server will be delivered to the user without losing any precision when requested.

Additional Information

Notice that the PR adds timestampPrecision: 12 only when the user explicitly uses the TIMESTAMP(12) types. This is because if we automatically opt users into timestampPrecision: 12 then their code will suddenly fail for certain queries that were working before. Therefore, we are going to make timestamp precision an opt-in property.

precision timestamps

…is/google-cloud-node into big-query-query-changes

alvarowolfx · 2026-02-05T19:58:43Z

handwritten/bigquery/src/job.ts

-          });
+          try {
+            /*
+            Without this try/catch block, calls to getRows will hang indefinitely if


nit: getRows = jobsQuery endpoint ?

Yes! This has been fixed now. This was a typo.

alvarowolfx · 2026-02-05T20:00:47Z

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

+import {describe, it, before} from 'mocha';
+import {BigQuery} from '../src';
+
+describe('High Precision Query System Tests', () => {


why do we need a separated file ? The previous PR we already deviated a bit from the pattern of having system tests in the https://github.com/googleapis/nodejs-bigquery/blob/main/system-test/bigquery.ts and added https://github.com/googleapis/nodejs-bigquery/blob/main/system-test/timestamp_output_format.ts, can we bundle all timestamp related tests into the same file ?

And gonna bring this again that we don't need the amount of combinations and system tests to check if the support for picosecond resolution is working. More tests doesn't necessarily means more coverage. With this PR and the previous one we are adding 28 query executions, where previously we had a total of around 50. Not saying that the coverage was perfect before, but adding too many system/integration test for a time format change seems bit too much, I'd lean more on unit tests. System tests makes CI slower, and I'm not seeing enough justification for the amount of combination and tests being added here.

We already got bitten by too much client side validation or tests trying to assert internal details of the service in the past that can cause problems. In this case, is not a SDK code, but is test that can fail in the future if things changes in the service.

See internal b/460198628

why do we need a separated file ?

I realize having a separate file deviates from the pattern of putting every test in system-test/bigquery.ts, but I really believe that having a separate file is a better pattern. One of the biggest drawbacks with putting every test in one file is that you lose encapsulation. For instance, the before/after hooks in the bigquery.ts test file don't have anything to do with the new tests we are adding. So if we add the new tests to this file then future maintainers have to think about how everything else in this file including the before/after hooks influence these tests and we don't want that.

we don't need the amount of combinations and system tests to check if the support for picosecond resolution is working

Ok. I needed the tests myself to understand how the client was behaving, but maybe now we can comment some of them out to improve the CI performance. I would prefer to comment the tests out rather than delete them though because the commented tests could be useful later when we want to investigate the product's behaviour. Which ones do you want to comment out?

alvarowolfx · 2026-02-05T20:01:17Z

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

+
+describe('High Precision Query System Tests', () => {
+  let bigquery: BigQuery;
+  const expectedTsValueMicroseconds = '2023-01-01T12:00:00.123456000Z';


I think this was suppose to be Nanosecond. We missed that the previous PR

Yes. Good catch. I changed this in both places.

alvarowolfx · 2026-02-05T20:01:26Z

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

+describe('High Precision Query System Tests', () => {
+  let bigquery: BigQuery;
+  const expectedTsValueMicroseconds = '2023-01-01T12:00:00.123456000Z';
+  const expectedTsValueNanoseconds = '2023-01-01T12:00:00.123456789123Z';


and this picosecond. Same applies to the previous https://github.com/googleapis/nodejs-bigquery/pull/1596/changes#diff-e82cb9428a68678cc305e12e59f2e21761622b9fcfcf45d4caab5e80657e2b9a test file

Yes. Good catch. I changed this in both places.

alvarowolfx · 2026-02-05T20:02:21Z

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

+      expectedTsValue: expectedTsValueMicroseconds,
+    },
+    {
+      name: 'TOF: FLOAT64, UI64: true (error)',


the service side is going to reject it and is not a reasonable combination that customers would use. Not sure if we need to assert this. If the service side changes behavior (and can happen) we are gonna have a flaky test. I'd add just one error combination here.

I commented this test out. Let me know if you want more tests commented out.

alvarowolfx · 2026-02-05T20:03:21Z

handwritten/bigquery/test/bigquery.ts

      assert.deepStrictEqual(req, expectedReq);
    });

    it('should create a QueryRequest from a SQL string', () => {


we can write similar tests to this one to assert the logic for default dataFormatOptions value. The existing tests assert only not passing any format from the customer and expecting ISO8601_STRING, but we can test passing any timestampOutputFormat or useInt64Timestamp and assert that this overrides the default value. This is faster than the system test and covers the change that is to use ISO8601_STRING as the default, depending on the format option provided by the customer

Now I understand your preference for unit tests. I'll get to this one next.

danieljbruce

Just need to follow up on one more PR comment.

danieljbruce · 2026-02-06T15:07:39Z

handwritten/bigquery/src/job.ts

-          });
+          try {
+            /*
+            Without this try/catch block, calls to getRows will hang indefinitely if


Yes! This has been fixed now. This was a typo.

danieljbruce · 2026-02-06T15:20:22Z

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

+import {describe, it, before} from 'mocha';
+import {BigQuery} from '../src';
+
+describe('High Precision Query System Tests', () => {


why do we need a separated file ?

I realize having a separate file deviates from the pattern of putting every test in system-test/bigquery.ts, but I really believe that having a separate file is a better pattern. One of the biggest drawbacks with putting every test in one file is that you lose encapsulation. For instance, the before/after hooks in the bigquery.ts test file don't have anything to do with the new tests we are adding. So if we add the new tests to this file then future maintainers have to think about how everything else in this file including the before/after hooks influence these tests and we don't want that.

we don't need the amount of combinations and system tests to check if the support for picosecond resolution is working

Ok. I needed the tests myself to understand how the client was behaving, but maybe now we can comment some of them out to improve the CI performance. I would prefer to comment the tests out rather than delete them though because the commented tests could be useful later when we want to investigate the product's behaviour. Which ones do you want to comment out?

danieljbruce · 2026-02-06T15:25:01Z

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

+
+describe('High Precision Query System Tests', () => {
+  let bigquery: BigQuery;
+  const expectedTsValueMicroseconds = '2023-01-01T12:00:00.123456000Z';


Yes. Good catch. I changed this in both places.

danieljbruce · 2026-02-06T15:26:27Z

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

+describe('High Precision Query System Tests', () => {
+  let bigquery: BigQuery;
+  const expectedTsValueMicroseconds = '2023-01-01T12:00:00.123456000Z';
+  const expectedTsValueNanoseconds = '2023-01-01T12:00:00.123456789123Z';


Yes. Good catch. I changed this in both places.

danieljbruce · 2026-02-06T15:29:57Z

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

+      expectedTsValue: expectedTsValueMicroseconds,
+    },
+    {
+      name: 'TOF: FLOAT64, UI64: true (error)',


I commented this test out. Let me know if you want more tests commented out.

danieljbruce · 2026-02-06T15:30:29Z

handwritten/bigquery/test/bigquery.ts

      assert.deepStrictEqual(req, expectedReq);
    });

    it('should create a QueryRequest from a SQL string', () => {


Now I understand your preference for unit tests. I'll get to this one next.

move over all code changes supporting high

aad102a

precision timestamps

danieljbruce changed the title ~~move over all code changes supporting high~~ feat: Add high precision TIMESTAMP values for queries Feb 5, 2026

danieljbruce added 2 commits February 5, 2026 11:22

feat: Add high precision TIMESTAMP values for queries

d4b2b0b

Merge branch 'big-query-query-changes' of https://github.com/googleap…

c369bdf

…is/google-cloud-node into big-query-query-changes

danieljbruce marked this pull request as ready for review February 5, 2026 19:56

danieljbruce requested a review from alvarowolfx February 5, 2026 19:56

alvarowolfx requested changes Feb 5, 2026

View reviewed changes

danieljbruce added 5 commits February 6, 2026 10:04

correct typo in comment

0c799a2

picoseconds / not nanoseconds

b033b9a

rename nanoseconds to picoseconds

5871908

nanoseconds not microseconds

d39d0a9

Add comment for non-meaningful use case

9b61a74

danieljbruce commented Feb 6, 2026

View reviewed changes

Conversation

danieljbruce commented Feb 5, 2026

Description

Impact

Testing

Additional Information

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danieljbruce left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants