Skip to content

docs(bigquery): document BigQueryOptions and BigQueryRetryConfig retry and timeout settings - #15128

Open
lqiu96 wants to merge 2 commits into
googleapis:mainfrom
lqiu96:docs/bq-2f-document-retry-and-timeout-config
Open

lqiu96 wants to merge 2 commits into
googleapis:mainfrom
lqiu96:docs/bq-2f-document-retry-and-timeout-config

Conversation

@lqiu96

@lqiu96 lqiu96 commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Documents the retry and timeout configuration entry points on BigQueryOptions and BigQueryRetryConfig:

  • Adds class Javadoc to BigQueryOptions distinguishing overall retry bounds (Builder.setRetrySettings) from per-attempt HTTP connect and read timeouts (Builder.setTransportOptions(HttpTransportOptions), 60-second default read timeout via getDefaultHttpTransportOptions()).
  • Documents Builder.setTransportOptions, Builder.setResultRetryAlgorithm (including default retry behavior and linking BigQueryException#isRetryable()), and getDefaultHttpTransportOptions().
  • Documents BigQueryRetryConfig and its builder methods, explaining why message-based retries exist (BigQuery returns transient failures like rate limits with non-5xx codes such as 403 or 400 or in job error payloads), clarifying its scope (job creation for all job types via JobOption.bigQueryRetryConfig(...) and query job status polling via Job.waitFor(BigQueryRetryConfig, RetryOption...), ignored for non-query jobs in waitFor), and clarifying case-insensitive substring matching (retryOnMessage) vs. lowercased full-string regex matching (retryOnRegEx).

Verified with mvn fmt:check, checkstyle:check@checkstyle, test-compile, and javadoc -Xdoclint:syntax,html,reference (zero new warnings).

@lqiu96
lqiu96 requested review from a team as code owners November 21, 2026 00:12

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds comprehensive Javadoc documentation to BigQueryOptions and BigQueryRetryConfig to clarify configuration options, retry behaviors, and transport settings. Feedback on the changes highlights a potential inaccuracy in the Javadoc for retryOnRegEx, which states that matching is case-insensitive but references Pattern.matches (which is case-sensitive by default). Clarification is requested to ensure the documentation accurately reflects the underlying implementation.

Comment on lines +81 to +84
* Adds regular expression patterns to retry on. Matching is case-insensitive and requires a
* full-string match via {@link java.util.regex.Pattern#matches(String, CharSequence)}, so
* patterns must match the entire error message rather than only a substring (for example,
* {@code ".*rate limit.*"} rather than {@code "rate limit"}).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The Javadoc states that matching is case-insensitive and requires a full-string match via Pattern.matches(String, CharSequence). However, Pattern.matches is case-sensitive by default. If the underlying implementation compiles the pattern with Pattern.CASE_INSENSITIVE, it does not use Pattern.matches directly. Please clarify whether the matching is indeed case-insensitive and correct the reference to Pattern.matches if a custom compiled Pattern is used instead.

References
  1. Update stale Javadoc comments to reflect new method behavior for improved clarity, rather than removing them.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant