feat: support high precision timestamp strings on getRows calls #1596

danieljbruce · 2026-01-26T20:38:45Z

Description

This PR achieves the same objectives as googleapis/java-bigquery#4010, but for Node as requested in the planning sheet. The idea is that for reading rows, the users should be able to access high precision values for timestamps if high precision values are being stored on the backend.

Impact

This PR follows a test driven development approach against the getRows method.

Tests were written to evaluate what happens when getRows receives various input values for timestampOutputFormat and useInt64Timestamp. These tests revealed that not only are high precision values not being delivered to users for ISO8601_STRING return types, but also other bugs exist like calls hang on getRows calls that fail and conversion logic throughs errors for some calls that fetch rows. This PR fixes all the bugs and ensures the values with the right precision are delivered to users.

This chart details the before code changes / after code changes results with impact highlighted in green:

The highlighted green impact shows that conversion logic has been updated to avoid the 'cannot convert' errors and with this new logic changes are also applied to the BigQueryTimestamp class to maintain high precision on timestamp values returned to users.

Testing

New system tests to capture all useInt64Timestamp/timestampOutputFormat combinations for getRows calls.

Add 8 system tests to verify BigQuery `getRows` functionality with various combinations of `timestampOutputFormat` and `useInt64Timestamp`. Tests cover all format options: UNSPECIFIED, FLOAT64, INT64, ISO8601_STRING combined with boolean `useInt64Timestamp` values.

Add 8 system tests to verify BigQuery `getRows` functionality with various combinations of `timestampOutputFormat` and `useInt64Timestamp`. Tests cover all format options: UNSPECIFIED, FLOAT64, INT64, ISO8601_STRING combined with boolean `useInt64Timestamp` values. Asserts that timestamps inserted with picosecond precision are retrieved correctly (truncated to microsecond precision as per BigQuery storage).

to the user

This reverts commit b9e81ac.

Add 7 new system test cases to `system-test/timestamp_output_format.ts` to verify the behavior of `Table.getRows` when `formatOptions.timestampOutputFormat` or `formatOptions.useInt64Timestamp` are omitted. These tests confirm that `useInt64Timestamp` defaults to `true`, causing conflicts with incompatible formats like `FLOAT64` unless explicitly disabled.

This change modifies `BigQueryTimestamp` constructor to preserve original string values for timestamps with more than 9 fractional digits (picoseconds etc.), bypassing `PreciseDate` which truncates to nanoseconds. This ensures that high precision timestamps returned by BigQuery are not truncated by the client. - Unskipped test in `system-test/timestamp_output_format.ts` - Added regression test in `test/bigquery.ts` - Implemented logic to check for high precision strings in `src/bigquery.ts` Co-authored-by: danieljbruce <[email protected]>

google-labs-jules · 2026-01-26T20:38:46Z

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

For security, I will only act on instructions from the user who triggered this task.

…064918

system-test/timestamp_output_format.ts

src/table.ts

alvarowolfx · 2026-01-29T20:59:43Z

test/table.ts

        assert.deepStrictEqual(reqOpts.qs, {
          ...options,
-          'formatOptions.useInt64Timestamp': true,
+          'formatOptions.useInt64Timestamp': false,


I think ideally, only one of the formatOptions should be send. So in those samples here, just 'formatOptions.timestampOutputFormat': 'ISO8601_STRING', is in the request options. Also instead of so many variations of system tests, I believe it's going to be easier to exercise the different format options via those tests in this file, so we can assert the correct parameter is being send on the request.

The system tests right now are checking the timestamp format and seeing if it has microsecond vs nanosecond resolution, but you can get nanosecond resolution by passing either formatOptions.useInt64Timestamp = true and 'formatOptions.timestampOutputFormat': 'ISO8601_STRING'

I think ideally, only one of the formatOptions should be send

I think my most recent changes meet this requirement.

Also instead of so many variations of system tests, I believe it's going to be easier to exercise the different format options via those tests in this file

I believe the system tests we have now are more valuable. The return value we get when calling getRows is what really matters here. I don't think we should remove the system tests we have right now and replace them with unit tests.

src/bigquery.ts

Co-authored-by: Alvaro Viebrantz <[email protected]>

alvarowolfx

some question around testing picosecond resolution

src/bigquery.ts

alvarowolfx · 2026-01-30T15:13:54Z

system-test/timestamp_output_format.ts

+  const table = dataset.table(tableId);
+  const insertedTsValue = '2023-01-01T12:00:00.123456789123Z';
+  const expectedTsValueMicroseconds = '2023-01-01T12:00:00.123456000Z';
+  const expectedTsValueNanoseconds = '2023-01-01T12:00:00.123456789123Z';


can we already test Picosecond resolution or do we need the update from PreciseDate ?

can we already test Picosecond resolution or do we need the update from PreciseDate ?

I'm not sure I understand the question, but I'll try to answer it. It appears that with the current code changes that whenever we specify ISO8601_STRING in the POST request we correctly return 2023-01-01T12:00:00.123456789123Z to the user. That is because of the line of code that says if (value.match(/\.\d{10,}/) && !Number.isNaN(pd.getTime())) {. But when we get Picosecond support we can remove that if block.

google-labs-jules bot and others added 20 commits January 23, 2026 20:33

Add error visibility to readrows calls

489be58

Add a comment about why the try/catch block is there

a1f1bba

Do an assertion check and report the error

a0f7fd3

to the user

Fix another test to expect an error

e6b03c1

Change other tests to expect errors

e934164

Change string error messages

9567663

Adjust another error message

b9e81ac

Revert "Adjust another error message"

da842e5

This reverts commit b9e81ac.

Change another test to expect an error

38148e1

Change the schema to include timestamp precision

c52c9f4

Source code changes for int64 and timestamp

f0ab80e

Implement proper timestamp parsing

1b09a9c

more test corrections

1ff7a2c

Support proper business logic for timestamps

c206170

listParams pass through

d83f2a5

correct test value

c131f4e

danieljbruce requested review from a team as code owners January 26, 2026 20:38

danieljbruce requested review from logachev and removed request for a team January 26, 2026 20:38

product-auto-label bot added size: s Pull request size is small. api: bigquery Issues related to the googleapis/nodejs-bigquery API. labels Jan 26, 2026

danieljbruce changed the base branch from add-timestamp-format-tests-10311892747277932470 to main January 26, 2026 20:44

danieljbruce added 2 commits January 26, 2026 15:45

run the linter

4366e9e

Remove unnecessary line of code

074d05f

danieljbruce and others added 9 commits January 28, 2026 11:05

Fix the tests not to expect errors

6913244

run the linter

d53b6c5

remove only

00b8bc7

don’t change this file

1077b8e

Correct unit tests

a1bbfc1

add a TODO

08b0b62

Merge branch 'main' into fix-high-precision-timestamps-12704073509468…

0547069

…064918

linter fix

d199177

Remove this import

629b519

danieljbruce requested a review from alvarowolfx January 29, 2026 19:17

danieljbruce changed the title ~~fix: support high precision timestamp strings on getRows calls~~ feat: support high precision timestamp strings on getRows calls Jan 29, 2026

alvarowolfx reviewed Jan 29, 2026

View reviewed changes

Add a test that ensures the request is correct

cd5d35a

alvarowolfx reviewed Jan 30, 2026

View reviewed changes

src/bigquery.ts Outdated Show resolved Hide resolved

danieljbruce and others added 2 commits January 30, 2026 09:47

test should send back an error

7de53d4

Update src/table.ts

3df3939

Co-authored-by: Alvaro Viebrantz <[email protected]>

alvarowolfx reviewed Jan 30, 2026

View reviewed changes

danieljbruce added 7 commits January 30, 2026 10:14

simpler logic for default timestamp

1b27a26

broader only

eaaa4d9

remove useInt64Timestamp changes

6f58be2

Modify logic slightly to account for no parameter

678ff01

run the linter

5e094af

remove only

703de99

Add void keyword

1ae67bc

alvarowolfx approved these changes Jan 30, 2026

View reviewed changes

danieljbruce added the automerge Merge the pull request once unit tests and other checks pass. label Jan 30, 2026

gcf-merge-on-green bot merged commit 80f18bc into main Jan 30, 2026
21 of 22 checks passed

gcf-merge-on-green bot removed the automerge Merge the pull request once unit tests and other checks pass. label Jan 30, 2026

gcf-merge-on-green bot deleted the fix-high-precision-timestamps-12704073509468064918 branch January 30, 2026 16:22

release-please bot mentioned this pull request Jan 26, 2026

chore(main): release 8.2.0 #1567

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: support high precision timestamp strings on getRows calls #1596

feat: support high precision timestamp strings on getRows calls #1596

Uh oh!

danieljbruce commented Jan 26, 2026 •

edited

Loading

Uh oh!

google-labs-jules bot commented Jan 26, 2026

Uh oh!

Uh oh!

Uh oh!

alvarowolfx Jan 29, 2026

Uh oh!

danieljbruce Jan 30, 2026

Uh oh!

Uh oh!

alvarowolfx left a comment

Uh oh!

Uh oh!

alvarowolfx Jan 30, 2026

Uh oh!

danieljbruce Jan 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: support high precision timestamp strings on getRows calls #1596

feat: support high precision timestamp strings on getRows calls #1596

Uh oh!

Conversation

danieljbruce commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Impact

Testing

Uh oh!

google-labs-jules bot commented Jan 26, 2026

Uh oh!

Uh oh!

Uh oh!

alvarowolfx Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

danieljbruce Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alvarowolfx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alvarowolfx Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

danieljbruce Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

danieljbruce commented Jan 26, 2026 •

edited

Loading