diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryOptions.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryOptions.java index b8b7994f8775..f15b8a20e7ff 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryOptions.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryOptions.java @@ -31,6 +31,18 @@ import io.opentelemetry.api.trace.Tracer; import java.util.Set; +/** + * Configuration options for creating a {@link BigQuery} client. + * + *

Configure overall retry bounds (such as maximum attempts, retry delays, and total timeout) via + * {@link Builder#setRetrySettings(com.google.api.gax.retrying.RetrySettings)}. Configure + * per-attempt HTTP connect and read timeouts via {@link + * Builder#setTransportOptions(TransportOptions)} with {@link HttpTransportOptions} (by default, + * {@link #getDefaultHttpTransportOptions()} sets a 60-second read timeout). + * + *

For message-based retries on job creation and query job status polling, see {@link + * BigQueryRetryConfig}. + */ public class BigQueryOptions extends ServiceOptions { private static final String API_SHORT_NAME = "BigQuery"; @@ -85,6 +97,12 @@ private Builder(BigQueryOptions options) { super(options); } + /** + * Sets the HTTP transport options, including per-attempt connect and read timeouts. + * + *

BigQuery supports only {@link HttpTransportOptions}. Passing any other {@link + * TransportOptions} implementation throws {@link IllegalArgumentException}. + */ @Override public Builder setTransportOptions(TransportOptions transportOptions) { if (!(transportOptions instanceof HttpTransportOptions)) { @@ -158,6 +176,15 @@ public Builder setOpenTelemetryTracer(Tracer tracer) { return this; } + /** + * Sets a custom {@link ResultRetryAlgorithm} to determine which exceptions or responses are + * retried on eligible RPCs. + * + *

If not set, {@code BigQueryOptions} uses the default BigQuery retry handler, which retries + * transient network exceptions and retryable errors (see {@link + * BigQueryException#isRetryable()}). Supplying a custom algorithm replaces that default + * behavior. + */ public Builder setResultRetryAlgorithm(ResultRetryAlgorithm resultRetryAlgorithm) { this.resultRetryAlgorithm = resultRetryAlgorithm; return this; @@ -211,6 +238,7 @@ public TransportOptions getDefaultTransportOptions() { } } + /** Returns the default {@link HttpTransportOptions} with a 60-second read timeout. */ public static HttpTransportOptions getDefaultHttpTransportOptions() { return HttpTransportOptions.newBuilder().setReadTimeout(DEFAULT_READ_API_TIME_OUT).build(); } diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryRetryConfig.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryRetryConfig.java index 2e1f7c0bdaa8..30357b0c5d84 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryRetryConfig.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryRetryConfig.java @@ -19,6 +19,30 @@ import com.google.common.collect.ImmutableSet; +/** + * Configures additional error-message and regular-expression retry rules for job creation (via + * {@link BigQuery.JobOption#bigQueryRetryConfig(BigQueryRetryConfig)} on {@link + * BigQuery#create(JobInfo, BigQuery.JobOption...)}) and query job status polling (via {@link + * Job#waitFor(BigQueryRetryConfig, com.google.cloud.RetryOption...)}). + * + *

BigQuery surfaces several transient errors (such as rate-limit failures) with non-5xx HTTP + * status codes (such as 403 or 400) or inside job error payloads that are not retried automatically + * by default HTTP status retries (see {@link BigQueryException#isRetryable()} and BigQuery API HTTP status and error + * codes). This class lets callers opt into retrying eligible calls when an error message + * matches configured substrings or patterns, such as the constants in {@link + * BigQueryErrorMessages}. + * + *

Rules match case-insensitively against the exception or response error message text rather + * than structured {@link BigQueryError#getReason()} codes directly. Job creation via {@link + * BigQuery.JobOption#bigQueryRetryConfig(BigQueryRetryConfig)} applies to all job types, whereas + * {@link Job#waitFor(BigQueryRetryConfig, com.google.cloud.RetryOption...)} applies this + * configuration only to query jobs and ignores it for non-query jobs. + * + * @see BigQueryErrorMessages + * @see BigQuery API HTTP status and + * error codes + */ public class BigQueryRetryConfig { private final ImmutableSet retriableErrorMessages; private final ImmutableSet retriableRegExes; @@ -28,10 +52,12 @@ private BigQueryRetryConfig(Builder builder) { retriableRegExes = builder.retriableRegExes.build(); } + /** Returns the configured error message substrings that trigger a retry. */ public ImmutableSet getRetriableErrorMessages() { return retriableErrorMessages; } + /** Returns the configured full-string regular expression patterns that trigger a retry. */ public ImmutableSet getRetriableRegExes() { return retriableRegExes; } @@ -43,6 +69,10 @@ public static class Builder { private Builder() {} + /** + * Adds error message substrings to retry on using a case-insensitive substring match against + * the exception or response error message text. + */ public final Builder retryOnMessage(String... errorMessages) { for (String errorMessage : errorMessages) { retriableErrorMessages.add(checkNotNull(errorMessage)); @@ -50,6 +80,13 @@ public final Builder retryOnMessage(String... errorMessages) { return this; } + /** + * Adds regular expression patterns to retry on. Both the pattern and the error message are + * lowercased before performing a full-string regular expression match, so patterns must match + * the entire error message rather than only a substring (for example, {@code ".*rate limit.*"} + * rather than {@code "rate limit"}) and should avoid uppercase regex character escapes such as + * {@code \D} or {@code \S}. + */ public final Builder retryOnRegEx(String... regExPatterns) { for (String regExPattern : regExPatterns) { retriableRegExes.add(checkNotNull(regExPattern));