Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,18 @@
import io.opentelemetry.api.trace.Tracer;
import java.util.Set;

/**
* Configuration options for creating a {@link BigQuery} client.
*
* <p>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).
*
* <p>For message-based retries on job creation and query job status polling, see {@link
* BigQueryRetryConfig}.
*/
public class BigQueryOptions extends ServiceOptions<BigQuery, BigQueryOptions> {

private static final String API_SHORT_NAME = "BigQuery";
Expand Down Expand Up @@ -85,6 +97,12 @@ private Builder(BigQueryOptions options) {
super(options);
}

/**
* Sets the HTTP transport options, including per-attempt connect and read timeouts.
*
* <p>BigQuery supports only {@link HttpTransportOptions}. Passing any other {@link
* TransportOptions} implementation throws {@link IllegalArgumentException}.
*/
@Override
public Builder setTransportOptions(TransportOptions transportOptions) {
if (!(transportOptions instanceof HttpTransportOptions)) {
Expand Down Expand Up @@ -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.
*
* <p>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;
Expand Down Expand Up @@ -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();
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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...)}).
*
* <p>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 <a
* href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and error
* codes</a>). 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}.
*
* <p>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 <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and
* error codes</a>
*/
public class BigQueryRetryConfig {
private final ImmutableSet<String> retriableErrorMessages;
private final ImmutableSet<String> retriableRegExes;
Expand All @@ -28,10 +52,12 @@ private BigQueryRetryConfig(Builder builder) {
retriableRegExes = builder.retriableRegExes.build();
}

/** Returns the configured error message substrings that trigger a retry. */
public ImmutableSet<String> getRetriableErrorMessages() {
return retriableErrorMessages;
}

/** Returns the configured full-string regular expression patterns that trigger a retry. */
public ImmutableSet<String> getRetriableRegExes() {
return retriableRegExes;
}
Expand All @@ -43,13 +69,24 @@ 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));
}
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));
Expand Down
Loading