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 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