From 61bca284d3ecfc25cb13128b5c63300723c75aec Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Sat, 21 Nov 2026 00:11:06 +0000 Subject: [PATCH 1/2] docs(bigquery): document async job retry semantics and JobException behavior --- .../com/google/cloud/bigquery/BigQuery.java | 50 +++++++++++++++---- .../java/com/google/cloud/bigquery/Job.java | 6 ++- .../google/cloud/bigquery/JobException.java | 13 ++++- .../com/google/cloud/bigquery/JobStatus.java | 6 +++ 4 files changed, 63 insertions(+), 12 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..c21a331a98a6 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 @@ -851,6 +851,13 @@ public int hashCode() { /** * Creates a new job. * + *

Job execution is asynchronous, and a failed job's {@link JobId} is terminal. If a job fails + * with a transient error, resubmit the work as a new job with a new {@link JobId} rather than + * polling the failed job again or reusing its {@link JobId}. See Repeating jobs + * and BigQuery API HTTP status and + * error codes for guidance on retryable job errors. + * *

Example of loading a newline-delimited-json file with textual fields from GCS to a table. * *

{@code
@@ -1593,6 +1600,12 @@ TableResult listTableData(
    * 

This method cannot be used in conjuction with {@link QueryJobConfiguration#dryRun()} * queries. Since dry-run queries are not actually executed, there's no way to retrieve results. * + *

Transient query job failures are not re-executed automatically on the same job. To retry a + * failed query, invoke this method again so a new job is submitted. See Repeating jobs + * and BigQuery API HTTP status and + * error codes. + * *

Example of running a query. * *

{@code
@@ -1609,10 +1622,11 @@ TableResult listTableData(
    * }
    * }
* - * @throws BigQueryException upon failure + * @throws BigQueryException upon failure, including when the job completes with an error * @throws InterruptedException if the current thread gets interrupted while waiting for the query * to complete - * @throws JobException if the job completes unsuccessfully + * @throws JobException declared for backwards compatibility only and never thrown by current + * client implementations (job failures throw {@link BigQueryException} instead) */ TableResult query(QueryJobConfiguration configuration, JobOption... options) throws InterruptedException, JobException; @@ -1626,13 +1640,20 @@ TableResult query(QueryJobConfiguration configuration, JobOption... options) *

This method cannot be used in conjunction with {@link QueryJobConfiguration#dryRun()} * queries. Since dry-run queries are not actually executed, there's no way to retrieve results. * + *

A failed {@code jobId} is terminal and cannot be reused to re-execute the query. Generate a + * new {@link JobId} when retrying a transient failure. See Repeating jobs + * and BigQuery API HTTP status and + * error codes. + * *

See {@link #query(QueryJobConfiguration, JobOption...)} for examples on populating a {@link * QueryJobConfiguration}. * - * @throws BigQueryException upon failure + * @throws BigQueryException upon failure, including when the job completes with an error * @throws InterruptedException if the current thread gets interrupted while waiting for the query * to complete - * @throws JobException if the job completes unsuccessfully + * @throws JobException declared for backwards compatibility only and never thrown by current + * client implementations (job failures throw {@link BigQueryException} instead) */ TableResult query(QueryJobConfiguration configuration, JobId jobId, JobOption... options) throws InterruptedException, JobException; @@ -1659,10 +1680,11 @@ TableResult query(QueryJobConfiguration configuration, JobId jobId, JobOption... * @param configuration the query configuration * @param options query options * @return an {@link ArrowQueryResult} streaming Arrow vectors - * @throws BigQueryException upon failure + * @throws BigQueryException upon failure, including when the job completes with an error * @throws InterruptedException if the current thread gets interrupted while waiting for the query * to complete - * @throws JobException if the job completes unsuccessfully + * @throws JobException declared for backwards compatibility only and never thrown by current + * client implementations (job failures throw {@link BigQueryException} instead) */ @BetaApi default ArrowQueryResult queryArrow(QueryJobConfiguration configuration, JobOption... options) @@ -1693,10 +1715,11 @@ default ArrowQueryResult queryArrow(QueryJobConfiguration configuration, JobOpti * @param jobId the job ID to use * @param options query options * @return an {@link ArrowQueryResult} streaming Arrow vectors - * @throws BigQueryException upon failure + * @throws BigQueryException upon failure, including when the job completes with an error * @throws InterruptedException if the current thread gets interrupted while waiting for the query * to complete - * @throws JobException if the job completes unsuccessfully + * @throws JobException declared for backwards compatibility only and never thrown by current + * client implementations (job failures throw {@link BigQueryException} instead) */ @BetaApi default ArrowQueryResult queryArrow( @@ -1715,13 +1738,20 @@ default ArrowQueryResult queryArrow( *

This method cannot be used in conjunction with {@link QueryJobConfiguration#dryRun()} * queries. Since dry-run queries are not actually executed, there's no way to retrieve results. * + *

A failed {@code jobId} is terminal and cannot be reused to re-execute the query. Generate a + * new {@link JobId} when retrying a transient failure. See Repeating jobs + * and BigQuery API HTTP status and + * error codes. + * *

See {@link #query(QueryJobConfiguration, JobOption...)} for examples on populating a {@link * QueryJobConfiguration}. * - * @throws BigQueryException upon failure + * @throws BigQueryException upon failure, including when the job completes with an error * @throws InterruptedException if the current thread gets interrupted while waiting for the query * to complete - * @throws JobException if the job completes unsuccessfully + * @throws JobException declared for backwards compatibility only and never thrown by current + * client implementations (job failures throw {@link BigQueryException} instead) */ Object queryWithTimeout( QueryJobConfiguration configuration, JobId jobId, Long timeoutMs, JobOption... options) 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..b24c5147b956 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 @@ -355,7 +355,11 @@ private Job waitForInternal(BigQueryRetryConfig bigQueryRetryConfig, RetryOption * the current {@code Job} instance is not updated. To get the new state, call {@link * #waitFor(RetryOption...)} or {@link #reload(JobOption...)}. * - * @throws BigQueryException upon failure + * @throws BigQueryException if the job completes with an error or an RPC error occurs + * @throws InterruptedException if the current thread gets interrupted while waiting for the query + * to complete + * @throws JobException declared for backwards compatibility only and never thrown by current + * client implementations (job failures throw {@link BigQueryException} instead) */ public TableResult getQueryResults(QueryResultsOption... options) throws InterruptedException, JobException { diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/JobException.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/JobException.java index 0bfa2572a30c..72d2de2a442b 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/JobException.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/JobException.java @@ -19,7 +19,18 @@ import com.google.common.collect.ImmutableList; import java.util.List; -/** Exception describing a failure of a job. */ +/** + * Exception describing a failure of a job. + * + *

Although {@link BigQuery#query(QueryJobConfiguration, BigQuery.JobOption...)}, {@link + * BigQuery#queryArrow(QueryJobConfiguration, BigQuery.JobOption...)}, {@link + * BigQuery#queryWithTimeout(QueryJobConfiguration, JobId, Long, BigQuery.JobOption...)}, and {@link + * Job#getQueryResults(BigQuery.QueryResultsOption...)} declare {@code JobException} in their {@code + * throws} clauses for backwards compatibility, this exception is never thrown by current client + * implementations, which report failed jobs by throwing {@link BigQueryException} instead. Callers + * should catch {@link BigQueryException} and inspect {@link BigQueryException#getError()} or {@link + * BigQueryException#getErrors()} to handle job failures. + */ public class JobException extends RuntimeException { private final JobId id; private final ImmutableList errors; diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/JobStatus.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/JobStatus.java index ecd48c375350..c23d11306cbe 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/JobStatus.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/JobStatus.java @@ -114,6 +114,12 @@ public State getState() { * Returns the final error result of the job. If present, indicates that the job has completed and * was unsuccessful. * + *

Once a job reaches {@link State#DONE} with an error, it cannot be resumed or re-executed by + * polling again or reusing the same {@link JobId}. To retry a transient job failure, inspect + * {@link BigQueryError#getReason()} and submit a new job with a new {@link JobId}. See Repeating + * jobs. + * * @see BigQuery API HTTP status and * error codes */ From 6d40ae2cf55c5920377c62a4474f1b9da9179e5a Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Sat, 21 Nov 2026 01:08:52 +0000 Subject: [PATCH 2/2] docs(bigquery): document terminal jobId retry semantics on queryArrow --- .../src/main/java/com/google/cloud/bigquery/BigQuery.java | 6 ++++++ 1 file changed, 6 insertions(+) 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 c21a331a98a6..a7e0e36e90d5 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 @@ -1711,6 +1711,12 @@ default ArrowQueryResult queryArrow(QueryJobConfiguration configuration, JobOpti * --add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED * }

* + *

A failed {@code jobId} is terminal and cannot be reused to re-execute the query. Generate a + * new {@link JobId} when retrying a transient failure. See Repeating jobs + * and BigQuery API HTTP status and + * error codes. + * * @param configuration the query configuration * @param jobId the job ID to use * @param options query options