Repository navigation
docs(bigquery): document async job retry semantics and JobException behavior #15130
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -851,6 +851,13 @@ public int hashCode() { | |||||||||||||||||
| /** | ||||||||||||||||||
| * Creates a new job. | ||||||||||||||||||
| * | ||||||||||||||||||
| * <p>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 <a | ||||||||||||||||||
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | ||||||||||||||||||
| * and <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | ||||||||||||||||||
| * error codes</a> for guidance on retryable job errors. | ||||||||||||||||||
| * | ||||||||||||||||||
| * <p>Example of loading a newline-delimited-json file with textual fields from GCS to a table. | ||||||||||||||||||
| * | ||||||||||||||||||
| * <pre>{@code | ||||||||||||||||||
|
|
@@ -1593,6 +1600,12 @@ TableResult listTableData( | |||||||||||||||||
| * <p>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. | ||||||||||||||||||
| * | ||||||||||||||||||
| * <p>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 <a | ||||||||||||||||||
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | ||||||||||||||||||
| * and <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | ||||||||||||||||||
| * error codes</a>. | ||||||||||||||||||
|
Comment on lines
+1604
to
+1607
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Use the canonical domain
Suggested change
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Keeping |
||||||||||||||||||
| * | ||||||||||||||||||
| * <p>Example of running a query. | ||||||||||||||||||
| * | ||||||||||||||||||
| * <pre>{@code | ||||||||||||||||||
|
|
@@ -1609,10 +1622,11 @@ TableResult listTableData( | |||||||||||||||||
| * } | ||||||||||||||||||
| * }</pre> | ||||||||||||||||||
| * | ||||||||||||||||||
| * @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) | |||||||||||||||||
| * <p>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. | ||||||||||||||||||
| * | ||||||||||||||||||
| * <p>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 <a | ||||||||||||||||||
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | ||||||||||||||||||
| * and <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | ||||||||||||||||||
| * error codes</a>. | ||||||||||||||||||
|
Comment on lines
+1644
to
+1647
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Use the canonical domain
Suggested change
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Keeping |
||||||||||||||||||
| * | ||||||||||||||||||
| * <p>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 | ||||||||||||||||||
| * }</pre> | ||||||||||||||||||
| * | ||||||||||||||||||
| * <p>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 <a | ||||||||||||||||||
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | ||||||||||||||||||
| * and <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | ||||||||||||||||||
| * error codes</a>. | ||||||||||||||||||
| * | ||||||||||||||||||
| * @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( | |||||||||||||||||
| * <p>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. | ||||||||||||||||||
| * | ||||||||||||||||||
| * <p>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 <a | ||||||||||||||||||
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | ||||||||||||||||||
| * and <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | ||||||||||||||||||
| * error codes</a>. | ||||||||||||||||||
|
Comment on lines
+1748
to
+1751
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Use the canonical domain
Suggested change
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Keeping |
||||||||||||||||||
| * | ||||||||||||||||||
| * <p>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) | ||||||||||||||||||
|
|
||||||||||||||||||
| Original file line number | Diff line number | Diff line change | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -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. | ||||||||||||||
| * | ||||||||||||||
| * <p>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 <a | ||||||||||||||
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating | ||||||||||||||
| * jobs</a>. | ||||||||||||||
|
Comment on lines
+119
to
+121
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Use the canonical domain
Suggested change
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Keeping |
||||||||||||||
| * | ||||||||||||||
| * @see <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | ||||||||||||||
| * error codes</a> | ||||||||||||||
| */ | ||||||||||||||
|
|
||||||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Use the canonical domain
cloud.google.cominstead ofdocs.cloud.google.comfor Google Cloud documentation links to avoid unnecessary redirects and ensure long-term link stability.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Keeping
docs.cloud.google.comhere because it is now the canonical Google Cloud documentation domain:https://docs.cloud.google.com/bigquery/docs/managing-jobsandhttps://docs.cloud.google.com/bigquery/docs/errorsreturn HTTP 200 with zero redirects and declare<link rel="canonical">ondocs.cloud.google.com, whereas thecloud.google.comequivalents return HTTP 301 redirecting todocs.cloud.google.com(consistent with #15110, #15116, and #15123).