Add table information to BigQueryStorageApiInsertError

[hekk-kaori-maeda]

What is the purpose of the change?

This change adds table identification capabilities to BigQueryStorageApiInsertError to help users identify and troubleshoot errors when using BigQuery Storage Write API, especially in pipelines that write to multiple tables.

Fixes #36831

What changes are included in this PR?

1. Added tableUrn field to BigQueryStorageApiInsertError

   • Format: projects/{project}/datasets/{dataset}/tables/{table}
   • Consistent with TableDestination.getTableUrn() format

2. Added convenience methods with lazy initialization

   • getProjectId(), getDatasetId(), getTableId()
   • Uses lazy initialization with caching for optimal performance

3. Updated BigQueryStorageApiInsertErrorCoder

   • Encode/decode tableUrn field

4. Updated all calling sites to pass tableUrn

   • StorageApiWriteUnshardedRecords.java (3 locations)
   • StorageApiWritesShardedRecords.java (3 locations)
   • StorageApiConvertMessages.java (2 locations)

This makes the API consistent with BigQueryInsertError (used by STREAMING_INSERTS method).

How was this change tested?

• ✅ Local unit tests: ./gradlew :sdks:java:io:google-cloud-platform:test --tests "*StorageApi*" (PASSED)
• ✅ Code formatting: ./gradlew :sdks:java:io:google-cloud-platform:spotlessApply (PASSED)
• ✅ Verified table information is correctly captured in production pipeline error logs

Was this change documented?

• [x] Code changes are self-documenting
• [ ] Javadoc updated (existing constructors and getters are self-explanatory)

Checklist

• [x] Mentions the appropriate issue: Fixes #36831
• [ ] Update CHANGES.md (will add if required by reviewers)
• [x] ICLA not required (small contribution)

[gemini-code-assist[bot]]

Summary of Changes

Hello @hekk-kaori-maeda, I'm Gemini Code Assist[^1]! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the debugging and error handling capabilities for the BigQuery Storage Write API by embedding table identification directly into BigQueryStorageApiInsertError objects. This enhancement allows users to quickly pinpoint which table an error originated from, especially in complex pipelines writing to multiple BigQuery tables, thereby streamlining troubleshooting processes.

Highlights

• Enhanced Error Information: The BigQueryStorageApiInsertError class now includes a tableUrn field, providing specific table identification for insertion errors.
• Convenience Accessors: New methods getProjectId(), getDatasetId(), and getTableId() have been added to BigQueryStorageApiInsertError for easy extraction of table components from the tableUrn, utilizing lazy initialization for performance.
• Serialization Update: The BigQueryStorageApiInsertErrorCoder has been updated to correctly encode and decode the new tableUrn field, ensuring data integrity across serialization.
• Widespread Integration: All relevant calling sites within StorageApiWriteUnshardedRecords, StorageApiWritesShardedRecords, and StorageApiConvertMessages have been modified to capture and pass the tableUrn when creating BigQueryStorageApiInsertError instances.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with :thumbsup: and :thumbsdown: on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

[^1]: Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

[github-actions[bot]]

Assigning reviewers:

R: @m-trieu for label java.

Note: If you would like to opt out of this review, comment assign to next reviewer.

Available commands:

• stop reviewer notifications - opt out of the automated review tooling
• remind me after tests pass - tag the comment author after tests pass
• waiting on author - shift the attention set back to the author (any comment or push by the author will return the attention set to the reviewers)

The PR bot will only process comments in the main thread (not review comments).

[stankiewicz]

@hekk-kaori-maeda I really like PR! To be more consistent with BigQueryInsertError please use TableReference as field and expose it.

[hekk-kaori-maeda]

@stankiewicz Thank you for the review! I've updated the implementation to use TableReference instead of String tableUrn, following the pattern used in BigQueryInsertError.

Changes made:

1. Changed to TableReference field

   • BigQueryStorageApiInsertError now uses TableReference table instead of String tableUrn
   • Removed custom parsing methods (getProjectId(), getDatasetId(), getTableId())
   • Added getTable() method that returns TableReference

2. Updated coder to use BigQueryHelpers

   • encode(): Uses BigQueryHelpers.toTableSpec() to convert TableReference → String
   • decode(): Uses BigQueryHelpers.parseTableSpec() to convert String → TableReference

3. Added null safety checks

   • Added null checks in the coder before calling toTableSpec() and parseTableSpec()
   • This prevents NullPointerException when table information is unavailable
   • Ensures pipeline stability even during error handling scenarios

4. Updated all calling sites

   • All instantiation sites now pass TableReference from TableDestination.getTableReference()
   • Files updated: StorageApiWriteUnshardedRecords.java, StorageApiWritesShardedRecords.java, StorageApiConvertMessages.java
   • Added TableReference imports to modified files

5. Updated toString() method

   • Added table field to the string representation for better debugging visibility
   • Ensures all fields are included in error logs

Ready for review.

[github-actions[bot]]

Reminder, please take a look at this pr: @m-trieu

[github-actions[bot]]

Assigning new set of reviewers because Pr has gone too long without review. If you would like to opt out of this review, comment assign to next reviewer:

R: @ahmedabu98 for label java.

Available commands:

• stop reviewer notifications - opt out of the automated review tooling
• remind me after tests pass - tag the comment author after tests pass
• waiting on author - shift the attention set back to the author (any comment or push by the author will return the attention set to the reviewers)

[github-actions[bot]]

Reminder, please take a look at this pr: @ahmedabu98

[hekk-kaori-maeda]

@ahmedabu98 Thank you for the review!

I've added unit tests for BigQueryStorageApiInsertErrorCoder in commit [a933d85].

The tests cover:

• Basic encode/decode with all fields populated
• Encode/decode with null table
• Encode/decode with null errorMessage
• Encode/decode with both nullable fields null

Regarding update compatibility Since BigQueryStorageApiInsertError is used for error handling and typically not persisted across pipeline updates, I believe the current implementation follows the existing patterns. However, if you'd like me to add backward compatibility (e.g., version flag or field count check), please let me know.

Could you also clarify your comment about "update compatibility"? I wasn't able to find the inline comment.

[github-actions[bot]]

Assigning new set of reviewers because Pr has gone too long without review. If you would like to opt out of this review, comment assign to next reviewer:

R: @kennknowles for label java.

Available commands:

• stop reviewer notifications - opt out of the automated review tooling
• remind me after tests pass - tag the comment author after tests pass
• waiting on author - shift the attention set back to the author (any comment or push by the author will return the attention set to the reviewers)

[github-actions[bot]]

Reminder, please take a look at this pr: @kennknowles