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..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 @@ -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)
@@ -1689,14 +1711,21 @@ 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 * @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 +1744,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 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
*/