From 599f26e8e4d44c193a5e35962e6725a0470f3edd Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Sat, 21 Nov 2026 00:11:04 +0000 Subject: [PATCH 1/3] docs(bigquery): document Job.waitFor and Job.reload errors vs. BigQuery.getJob --- .../com/google/cloud/bigquery/BigQuery.java | 8 ++ .../java/com/google/cloud/bigquery/Job.java | 110 +++++++++++------- .../java/com/google/cloud/bigquery/Table.java | 52 +++++---- 3 files changed, 108 insertions(+), 62 deletions(-) diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQuery.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQuery.java index ce35876a7517..0db4760f612d 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQuery.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQuery.java @@ -1485,6 +1485,10 @@ TableResult listTableData( * Returns the requested job or {@code null} if not found. If the location of the job is not "US" * or "EU", {@link #getJob(JobId, JobOption...)} must be used instead. * + *

Unlike {@link Job#reload(JobOption...)} and {@link Job#waitFor(RetryOption...)}, this method + * returns the {@link Job} even when {@link JobStatus#getError()} is non-null, allowing callers to + * inspect job errors without catching {@link BigQueryException}. + * *

Example of getting a job. * *

{@code
@@ -1503,6 +1507,10 @@ TableResult listTableData(
    * Returns the requested job or {@code null} if not found. If the location of the job is not "US"
    * or "EU", the {@code jobId} must specify the job location.
    *
+   * 

Unlike {@link Job#reload(JobOption...)} and {@link Job#waitFor(RetryOption...)}, this method + * returns the {@link Job} even when {@link JobStatus#getError()} is non-null, allowing callers to + * inspect job errors without catching {@link BigQueryException}. + * *

Example of getting a job. * *

{@code
diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java
index 503c91dc3209..2d01062dc39a 100644
--- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java
+++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java
@@ -238,47 +238,64 @@ private boolean hasDoneState() {
     return getStatus() != null && JobStatus.State.DONE.equals(getStatus().getState());
   }
 
-  /** See {@link #waitFor(BigQueryRetryConfig, RetryOption...)} */
+  /**
+   * See {@link #waitFor(BigQueryRetryConfig, RetryOption...)}. Uses the default query retry
+   * configuration, which retries on {@link BigQueryErrorMessages#RATE_LIMIT_EXCEEDED_MSG}.
+   */
   public Job waitFor(RetryOption... waitOptions) throws InterruptedException {
     return waitForInternal(DEFAULT_RETRY_CONFIG, waitOptions);
   }
 
   /**
-   * Blocks until this job completes its execution, either failing or succeeding. This method
-   * returns current job's latest information. If the job no longer exists, this method returns
-   * {@code null}. By default, the job status is checked using jittered exponential backoff with 1
-   * second as an initial delay, 2.0 as a backoff factor, 1 minute as maximum delay between polls,
-   * 12 hours as a total timeout and unlimited number of attempts. For query jobs, the job status
-   * check can be configured to retry on specific BigQuery error messages using {@link
-   * BigQueryRetryConfig}. This {@link BigQueryRetryConfig} configuration is not available for
-   * non-query jobs.
+   * Blocks until this job completes its execution and returns the latest {@link Job} snapshot, or
+   * {@code null} if the job no longer exists.
+   *
+   * 

If the job completes with an execution error, this method throws {@link BigQueryException} + * (via {@link #reload(JobOption...)}) rather than returning a {@code Job} with a non-null {@link + * JobStatus#getError()}. Catch {@link BigQueryException} to handle job failures. To inspect a + * failed job's {@link JobStatus} without throwing, use {@link BigQuery#getJob(JobId, + * BigQuery.JobOption...)}. + * + *

By default, job status is polled with jittered backoff until the job completes or the + * default total wait timeout expires. Pass {@link RetryOption} arguments (such as {@link + * RetryOption#initialRetryDelayDuration(Duration)} and {@link + * RetryOption#totalTimeoutDuration(Duration)}) to override polling delays or the total timeout. + * For query jobs, status checks can also be configured to retry on specific BigQuery error + * messages using {@link BigQueryRetryConfig} and constants in {@link BigQueryErrorMessages} (by + * default, {@link #waitFor(RetryOption...)} retries on {@link + * BigQueryErrorMessages#RATE_LIMIT_EXCEEDED_MSG}). This {@link BigQueryRetryConfig} configuration + * is not available for non-query jobs. * *

Example usage of {@code waitFor()}. * *

{@code
-   * Job completedJob = job.waitFor();
-   * if (completedJob == null) {
-   *   // job no longer exists
-   * } else if (completedJob.getStatus().getError() != null) {
-   *   // job failed, handle error
-   * } else {
-   *   // job completed successfully
+   * try {
+   *   Job completedJob = job.waitFor();
+   *   if (completedJob == null) {
+   *     // job no longer exists
+   *   } else {
+   *     // job completed successfully
+   *   }
+   * } catch (BigQueryException e) {
+   *   // job failed, polling timed out, or RPC failed
    * }
    * }
* *

Example usage of {@code waitFor()} with checking period and timeout. * *

{@code
-   * Job completedJob =
-   *     job.waitFor(
-   *         RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
-   *         RetryOption.totalTimeout(Duration.ofMinutes(1)));
-   * if (completedJob == null) {
-   *   // job no longer exists
-   * } else if (completedJob.getStatus().getError() != null) {
-   *   // job failed, handle error
-   * } else {
-   *   // job completed successfully
+   * try {
+   *   Job completedJob =
+   *       job.waitFor(
+   *           RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
+   *           RetryOption.totalTimeout(Duration.ofMinutes(1)));
+   *   if (completedJob == null) {
+   *     // job no longer exists
+   *   } else {
+   *     // job completed successfully
+   *   }
+   * } catch (BigQueryException e) {
+   *   // job failed, polling timed out, or RPC failed
    * }
    * }
* @@ -286,25 +303,29 @@ public Job waitFor(RetryOption... waitOptions) throws InterruptedException { * exceeded error messages for query jobs. * *
{@code
-   * Job completedJob =
-   *     job.waitFor(
-   *             BigQueryRetryConfig.newBuilder()
-   *                 .retryOnMessage(BigQueryErrorMessages.RATE_LIMIT_EXCEEDED_MSG)
-   *                 .retryOnMessage(BigQueryErrorMessages.JOB_RATE_LIMIT_EXCEEDED_MSG)
-   *                 .retryOnRegEx(BigQueryErrorMessages.RetryRegExPatterns.RATE_LIMIT_EXCEEDED_REGEX)
-   *                 .build());
-   * if (completedJob == null) {
-   *   // job no longer exists
-   * } else if (completedJob.getStatus().getError() != null) {
-   *   // job failed, handle error
-   * } else {
-   *   // job completed successfully
+   * try {
+   *   Job completedJob =
+   *       job.waitFor(
+   *           BigQueryRetryConfig.newBuilder()
+   *               .retryOnMessage(BigQueryErrorMessages.RATE_LIMIT_EXCEEDED_MSG)
+   *               .retryOnMessage(BigQueryErrorMessages.JOB_RATE_LIMIT_EXCEEDED_MSG)
+   *               .retryOnRegEx(BigQueryErrorMessages.RetryRegExPatterns.RATE_LIMIT_EXCEEDED_REGEX)
+   *               .build());
+   *   if (completedJob == null) {
+   *     // job no longer exists
+   *   } else {
+   *     // job completed successfully
+   *   }
+   * } catch (BigQueryException e) {
+   *   // job failed, polling timed out, or RPC failed
    * }
    * }
* * @param bigQueryRetryConfig configures retries for query jobs for BigQuery failures * @param waitOptions options to configure checking period and timeout - * @throws BigQueryException upon failure, check {@link BigQueryException#getCause()} for details + * @throws BigQueryException if the job completes with an error, polling times out, or an RPC + * error occurs (inspect {@link BigQueryException#getError()}, {@link + * BigQueryException#getErrors()}, and {@link BigQueryException#getCause()}) * @throws InterruptedException if the current thread gets interrupted while waiting for the job * to complete */ @@ -585,7 +606,12 @@ public boolean shouldRetry(Throwable prevThrowable, Job prevResponse) { } /** - * Fetches current job's latest information. Returns {@code null} if the job does not exist. + * Fetches current job's latest information and returns a new {@code Job} snapshot, or {@code + * null} if the job does not exist. + * + *

If the fetched job has a non-null {@link JobStatus#getError()}, this method throws {@link + * BigQueryException} rather than returning the failed {@code Job}. To inspect a failed job's + * {@link JobStatus} without throwing, call {@link BigQuery#getJob(JobId, BigQuery.JobOption...)}. * *

Example of reloading all fields until job status is DONE. * @@ -607,7 +633,7 @@ public boolean shouldRetry(Throwable prevThrowable, Job prevResponse) { * * @param options job options * @return a {@code Job} object with latest information or {@code null} if not found - * @throws BigQueryException upon failure + * @throws BigQueryException if the job completed with an error or an RPC error occurs */ public Job reload(JobOption... options) { checkNotDryRun("reload"); diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Table.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Table.java index 5e9206450b1e..fc6099527b0b 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Table.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Table.java @@ -456,11 +456,13 @@ public TableResult list(Schema schema, TableDataListOption... options) throws Bi * try { * Job completedJob = job.waitFor(RetryOption.initialRetryDelay(Duration.ofSeconds(1)), * RetryOption.totalTimeout(Duration.ofMinutes(3))); - * if (completedJob != null && completedJob.getStatus().getError() == null) { - * // Job completed successfully + * if (completedJob == null) { + * // Job no longer exists * } else { - * // Handle error case + * // Job completed successfully * } + * } catch (BigQueryException e) { + * // Handle error case * } catch (InterruptedException e) { * // Handle interrupted wait * } @@ -492,11 +494,13 @@ public Job copy(String destinationDataset, String destinationTable, JobOption... * try { * Job completedJob = job.waitFor(RetryOption.initialRetryDelay(Duration.ofSeconds(1)), * RetryOption.totalTimeout(Duration.ofMinutes(3))); - * if (completedJob != null && completedJob.getStatus().getError() == null) { - * // Job completed successfully. + * if (completedJob == null) { + * // Job no longer exists. * } else { - * // Handle error case. + * // Job completed successfully. * } + * } catch (BigQueryException e) { + * // Handle error case. * } catch (InterruptedException e) { * // Handle interrupted wait * } @@ -525,11 +529,13 @@ public Job copy(TableId destinationTable, JobOption... options) throws BigQueryE * try { * Job completedJob = job.waitFor(RetryOption.initialRetryDelay(Duration.ofSeconds(1)), * RetryOption.totalTimeout(Duration.ofMinutes(3))); - * if (completedJob != null && completedJob.getStatus().getError() == null) { - * // Job completed successfully + * if (completedJob == null) { + * // Job no longer exists * } else { - * // Handle error case + * // Job completed successfully * } + * } catch (BigQueryException e) { + * // Handle error case * } catch (InterruptedException e) { * // Handle interrupted wait * } @@ -564,11 +570,13 @@ public Job extract(String format, String destinationUri, JobOption... options) * try { * Job completedJob = job.waitFor(RetryOption.initialRetryDelay(Duration.ofSeconds(1)), * RetryOption.totalTimeout(Duration.ofMinutes(3))); - * if (completedJob != null && completedJob.getStatus().getError() == null) { - * // Job completed successfully + * if (completedJob == null) { + * // Job no longer exists * } else { - * // Handle error case + * // Job completed successfully * } + * } catch (BigQueryException e) { + * // Handle error case * } catch (InterruptedException e) { * // Handle interrupted wait * } @@ -599,12 +607,14 @@ public Job extract(String format, List destinationUris, JobOption... opt * // Wait for the job to complete * try { * Job completedJob = job.waitFor(RetryOption.initialRetryDelay(Duration.ofSeconds(1)), - * RetryOption.totalTimeout(Duration.ofMinutes(3))); - * if (completedJob != null && completedJob.getStatus().getError() == null) { - * // Job completed successfully + * RetryOption.totalTimeout(Duration.ofMinutes(3))); + * if (completedJob == null) { + * // Job no longer exists * } else { - * // Handle error case + * // Job completed successfully * } + * } catch (BigQueryException e) { + * // Handle error case * } catch (InterruptedException e) { * // Handle interrupted wait * } @@ -638,17 +648,19 @@ public Job load(FormatOptions format, String sourceUri, JobOption... options) * try { * Job completedJob = job.waitFor(RetryOption.initialRetryDelay(Duration.ofSeconds(1)), * RetryOption.totalTimeout(Duration.ofMinutes(3))); - * if (completedJob != null && completedJob.getStatus().getError() == null) { - * // Job completed successfully + * if (completedJob == null) { + * // Job no longer exists * } else { - * // Handle error case + * // Job completed successfully * } + * } catch (BigQueryException e) { + * // Handle error case * } catch (InterruptedException e) { * // Handle interrupted wait * } * }

* - * @param format the format of the exported data + * @param format the format of the data to load * @param sourceUris the fully-qualified Google Cloud Storage URIs (e.g. gs://bucket/path) from * which to load the data * @param options job options From 347b26402b550f8e6bbf9f7aa6bed9422c9c6136 Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Sat, 21 Nov 2026 01:08:49 +0000 Subject: [PATCH 2/3] docs(bigquery): use non-obsolete RetryOption duration methods in examples --- .../java/com/google/cloud/bigquery/Job.java | 4 ++-- .../java/com/google/cloud/bigquery/Table.java | 24 +++++++++---------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java index 2d01062dc39a..2f1490978da1 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java @@ -287,8 +287,8 @@ public Job waitFor(RetryOption... waitOptions) throws InterruptedException { * try { * Job completedJob = * job.waitFor( - * RetryOption.initialRetryDelay(Duration.ofSeconds(1)), - * RetryOption.totalTimeout(Duration.ofMinutes(1))); + * RetryOption.initialRetryDelayDuration(Duration.ofSeconds(1)), + * RetryOption.totalTimeoutDuration(Duration.ofMinutes(1))); * if (completedJob == null) { * // job no longer exists * } else { diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Table.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Table.java index fc6099527b0b..f950cbabed84 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Table.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Table.java @@ -454,8 +454,8 @@ public TableResult list(Schema schema, TableDataListOption... options) throws Bi * Job job = table.copy(datasetName, tableName); * // Wait for the job to complete. * try { - * Job completedJob = job.waitFor(RetryOption.initialRetryDelay(Duration.ofSeconds(1)), - * RetryOption.totalTimeout(Duration.ofMinutes(3))); + * Job completedJob = job.waitFor(RetryOption.initialRetryDelayDuration(Duration.ofSeconds(1)), + * RetryOption.totalTimeoutDuration(Duration.ofMinutes(3))); * if (completedJob == null) { * // Job no longer exists * } else { @@ -492,8 +492,8 @@ public Job copy(String destinationDataset, String destinationTable, JobOption... * Job job = table.copy(destinationId, options); * // Wait for the job to complete. * try { - * Job completedJob = job.waitFor(RetryOption.initialRetryDelay(Duration.ofSeconds(1)), - * RetryOption.totalTimeout(Duration.ofMinutes(3))); + * Job completedJob = job.waitFor(RetryOption.initialRetryDelayDuration(Duration.ofSeconds(1)), + * RetryOption.totalTimeoutDuration(Duration.ofMinutes(3))); * if (completedJob == null) { * // Job no longer exists. * } else { @@ -527,8 +527,8 @@ public Job copy(TableId destinationTable, JobOption... options) throws BigQueryE * Job job = table.extract(format, gcsUrl); * // Wait for the job to complete * try { - * Job completedJob = job.waitFor(RetryOption.initialRetryDelay(Duration.ofSeconds(1)), - * RetryOption.totalTimeout(Duration.ofMinutes(3))); + * Job completedJob = job.waitFor(RetryOption.initialRetryDelayDuration(Duration.ofSeconds(1)), + * RetryOption.totalTimeoutDuration(Duration.ofMinutes(3))); * if (completedJob == null) { * // Job no longer exists * } else { @@ -568,8 +568,8 @@ public Job extract(String format, String destinationUri, JobOption... options) * Job job = table.extract(format, destinationUris); * // Wait for the job to complete * try { - * Job completedJob = job.waitFor(RetryOption.initialRetryDelay(Duration.ofSeconds(1)), - * RetryOption.totalTimeout(Duration.ofMinutes(3))); + * Job completedJob = job.waitFor(RetryOption.initialRetryDelayDuration(Duration.ofSeconds(1)), + * RetryOption.totalTimeoutDuration(Duration.ofMinutes(3))); * if (completedJob == null) { * // Job no longer exists * } else { @@ -606,8 +606,8 @@ public Job extract(String format, List destinationUris, JobOption... opt * Job job = table.load(FormatOptions.csv(), sourceUri); * // Wait for the job to complete * try { - * Job completedJob = job.waitFor(RetryOption.initialRetryDelay(Duration.ofSeconds(1)), - * RetryOption.totalTimeout(Duration.ofMinutes(3))); + * Job completedJob = job.waitFor(RetryOption.initialRetryDelayDuration(Duration.ofSeconds(1)), + * RetryOption.totalTimeoutDuration(Duration.ofMinutes(3))); * if (completedJob == null) { * // Job no longer exists * } else { @@ -646,8 +646,8 @@ public Job load(FormatOptions format, String sourceUri, JobOption... options) * Job job = table.load(FormatOptions.csv(), sourceUris); * // Wait for the job to complete * try { - * Job completedJob = job.waitFor(RetryOption.initialRetryDelay(Duration.ofSeconds(1)), - * RetryOption.totalTimeout(Duration.ofMinutes(3))); + * Job completedJob = job.waitFor(RetryOption.initialRetryDelayDuration(Duration.ofSeconds(1)), + * RetryOption.totalTimeoutDuration(Duration.ofMinutes(3))); * if (completedJob == null) { * // Job no longer exists * } else { From c63a5e80d34e840befb09b95b5fb647f9bc71966 Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Sat, 21 Nov 2026 03:15:30 +0000 Subject: [PATCH 3/3] docs(bigquery): clarify query vs non-query waitFor timeout and 404 behavior --- .../java/com/google/cloud/bigquery/Job.java | 21 +++++++++++-------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java index 2f1490978da1..b0ddc1e515e9 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java @@ -247,8 +247,9 @@ public Job waitFor(RetryOption... waitOptions) throws InterruptedException { } /** - * Blocks until this job completes its execution and returns the latest {@link Job} snapshot, or - * {@code null} if the job no longer exists. + * Blocks until this job completes its execution and returns the latest {@link Job} snapshot. If + * the job no longer exists, non-query jobs return {@code null} while query jobs throw {@link + * BigQueryException}. * *

If the job completes with an execution error, this method throws {@link BigQueryException} * (via {@link #reload(JobOption...)}) rather than returning a {@code Job} with a non-null {@link @@ -260,11 +261,13 @@ public Job waitFor(RetryOption... waitOptions) throws InterruptedException { * default total wait timeout expires. Pass {@link RetryOption} arguments (such as {@link * RetryOption#initialRetryDelayDuration(Duration)} and {@link * RetryOption#totalTimeoutDuration(Duration)}) to override polling delays or the total timeout. - * For query jobs, status checks can also be configured to retry on specific BigQuery error - * messages using {@link BigQueryRetryConfig} and constants in {@link BigQueryErrorMessages} (by - * default, {@link #waitFor(RetryOption...)} retries on {@link - * BigQueryErrorMessages#RATE_LIMIT_EXCEEDED_MSG}). This {@link BigQueryRetryConfig} configuration - * is not available for non-query jobs. + * If the total wait timeout expires before completion, non-query jobs throw {@link + * BigQueryException}, whereas query jobs return the current (still running) {@link Job} snapshot, + * so callers passing a short timeout should check {@link JobStatus#getState()}. For query jobs, + * status checks can also be configured to retry on specific BigQuery error messages using {@link + * BigQueryRetryConfig} and constants in {@link BigQueryErrorMessages} (by default, {@link + * #waitFor(RetryOption...)} retries on {@link BigQueryErrorMessages#RATE_LIMIT_EXCEEDED_MSG}). + * This {@link BigQueryRetryConfig} configuration is not available for non-query jobs. * *

Example usage of {@code waitFor()}. * @@ -323,8 +326,8 @@ public Job waitFor(RetryOption... waitOptions) throws InterruptedException { * * @param bigQueryRetryConfig configures retries for query jobs for BigQuery failures * @param waitOptions options to configure checking period and timeout - * @throws BigQueryException if the job completes with an error, polling times out, or an RPC - * error occurs (inspect {@link BigQueryException#getError()}, {@link + * @throws BigQueryException if the job completes with an error, a non-query job polling timeout + * expires, or an RPC error occurs (inspect {@link BigQueryException#getError()}, {@link * BigQueryException#getErrors()}, and {@link BigQueryException#getCause()}) * @throws InterruptedException if the current thread gets interrupted while waiting for the job * to complete