feat(bigquery-jdbc): support picosecond timestamps in Arrow Storage Read API and nested types

[keshavdandeva]

b/544839155

This PR enables picosecond precision (TIMESTAMP(12)) support across the BigQuery Storage Read API (Arrow stream) and nested data structures (ARRAY, STRUCT, and RANGE) when EnableTimestampPicos=true.

Key Changes

• Storage Read API Session Configuration: Configured TableReadOptions.arrowSerializationOptions with TIMESTAMP_PRECISION_PICOS in BigQueryStatement when EnableTimestampPicos is active.
• Arrow Deserialization & Formatting:
  • Wired enableTimestampPicos into BigQueryArrowResultSet, formatting picosecond timestamps directly to 12 fractional digits for column retrieval.
  • Normalized Arrow Text instances to String across hot paths to prevent downstream BigQueryTypeRegistry conversion failures.
  • Formatted RANGE and nested RANGE bounds using schema-derived element types and precision flags.
• Nested Types Propagation:
  • Propagated precision flags to BigQueryArrowArray and BigQueryArrowStruct.
  • Overrode getTargetClass() in BigQueryArrowArray to return String.class when picoseconds are enabled, preventing Array.newInstance mismatch exceptions.
• Unit Tests:
  • Added unit test suites verifying picosecond vs. microsecond behavior across BigQueryArrowResultSet, BigQueryArrowArrayOfPrimitives, BigQueryArrowStruct, and BigQueryStatement.

[gemini-code-assist]

Code Review

This pull request adds support for picosecond timestamp precision when retrieving Arrow data in the BigQuery JDBC driver. It propagates the enableTimestampPicos flag through BigQueryArrowArray, BigQueryArrowResultSet, and BigQueryArrowStruct, configures the Arrow serialization options in BigQueryStatement, and formats timestamps with high precision when enabled. Comprehensive unit tests are also added to verify this behavior. The review feedback suggests improving the robustness of getRangeElementType in BigQueryArrowResultSet by standardizing the type name to uppercase and adding a null check to prevent a potential NullPointerException when range bounds are unbounded.

[keshavdandeva]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds support for picosecond timestamp precision when reading Arrow data in the BigQuery JDBC driver. It propagates the 'enableTimestampPicos' flag across Arrow-related classes (BigQueryArrowArray, BigQueryArrowResultSet, BigQueryArrowStruct), configures ArrowSerializationOptions in BigQueryStatement, and updates BigQueryTemporalUtility to format timestamps with up to 12 fractional digits. The review feedback suggests making the range element type resolution more robust by converting the type string to uppercase before parsing, and warns about potential memory leaks in the unit tests due to unclosed RootAllocator and VectorSchemaRoot instances.

[logachev]

In what instances statement can be null? Feels weird that we explicitly pass enableTimestampPicos, but instantly override it. Should it be responsibility of the object instantiating this?

[keshavdandeva]

So, statement can be null in getNestedResultSet(...) (used when an Array column is unnested into a child ResultSet via Array.getResultSet(), where no statement object is present) and in the no-arg constructor.

But yeah I guess doing it in constructor is awkward, moved it to of(...) method

[logachev]

Why special case for Text here? Is it related to picoseconds in some way?

[keshavdandeva]

Yes, so in Storage Read API:

• standard timestamps (<= 6 digits) are transmitted in Arrow as 64-bit integers (TimeStampMicroVector).
• picosecond timestamps are transmitted as as VarCharVectors

So, calling VarCharVector.getObject() returns an org.apache.arrow.vector.util.Text and we convert that to String