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