Google BigQuery v2 API - Class BigQueryJob (3.9.0) 

public sealed class BigQueryJob

Reference documentation and code samples for the Google BigQuery v2 API class BigQueryJob.

An asynchronous job within BigQuery.

Inheritance

object > BigQueryJob

Namespace

Google.Cloud.BigQuery.V2

Assembly

Google.Cloud.BigQuery.V2.dll

Remarks

This class wraps the underlying REST API resource and retains a reference to the original client, allowing for simpler job-oriented operations.

Constructors

BigQueryJob(BigQueryClient, Job)

public BigQueryJob(BigQueryClient client, Job resource)

Constructs a new job.

Parameters
Name Description
client BigQueryClient

The client to use for operations on the job. Must not be null.
resource Job

The REST-ful resource representing the job. Must not be null.
Remarks

This is public to allow tests to construct instances for production code to consume; production code should not normally construct instances itself.

Properties

Reference

public JobReference Reference { get; }

The fully-qualified identifier for the job. This is short-hand for Resource.JobReference.

Property Value
Type Description
JobReference
Remarks

The properties within the reference can be used to determine the project ID and job ID components.

Resource

public Job Resource { get; }

The underlying REST-ful resource for the job.

Property Value
Type Description
Job
Remarks

The data within the resource may be incomplete, depending on how it was obtained.

State

public JobState State { get; }

The state of the job.

Property Value
Type Description
JobState

Statistics

public JobStatistics Statistics { get; }

The statistics of the job. This is short-hand for Resource.Statistics.

Property Value
Type Description
JobStatistics

Status

public JobStatus Status { get; }

The full status of the job, including any errors. This is short-hand for Resource.Status.

Property Value
Type Description
JobStatus

Methods

Cancel(CancelJobOptions)

public BigQueryJob Cancel(CancelJobOptions options = null)

Cancels this job. This method just creates a JobReference and delegates to CancelJob(JobReference, CancelJobOptions).

Parameter
Name Description
options CancelJobOptions

The options for the operation. May be null, in which case defaults will be supplied.
Returns
Type Description
BigQueryJob

The final state of the job.
Example

See BigQueryClient.CancelJob for an example using BigQueryClient.

CancelAsync(CancelJobOptions, CancellationToken)

public Task<BigQueryJob> CancelAsync(CancelJobOptions options = null, CancellationToken cancellationToken = default)

Asynchronously cancels this job. This method just creates a JobReference and delegates to CancelJobAsync(JobReference, CancelJobOptions, CancellationToken).

Parameters
Name Description
options CancelJobOptions

The options for the operation. May be null, in which case defaults will be supplied.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
TaskBigQueryJob

A task representing the asynchronous operation. When complete, the result is the final state of the job.
Example

See BigQueryClient.CancelJob for an example using BigQueryClient.

Delete(DeleteJobOptions)

public void Delete(DeleteJobOptions options = null)

Deletes this job. This method just creates a JobReference and delegates to DeleteJob(JobReference, DeleteJobOptions).

Parameter
Name Description
options DeleteJobOptions

The options for the operation. May be null, in which case defaults will be supplied.

DeleteAsync(DeleteJobOptions, CancellationToken)

public Task DeleteAsync(DeleteJobOptions options = null, CancellationToken cancellationToken = default)

Asynchronously deletes this job. This method just creates a JobReference and delegates to DeleteJobAsync(JobReference, DeleteJobOptions, CancellationToken).

Parameters
Name Description
options DeleteJobOptions

The options for the operation. May be null, in which case defaults will be supplied.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
Task

A task representing the asynchronous operation. When complete, the result is the final state of the job.

GetQueryResults(GetQueryResultsOptions)

public BigQueryResults GetQueryResults(GetQueryResultsOptions options = null)

Retrieves the result of this job, which must be a query job. This method just creates a JobReference and delegates to GetQueryResults(JobReference, GetQueryResultsOptions).

Parameter
Name Description
options GetQueryResultsOptions

The options for the operation. May be null, in which case defaults will be supplied.
Returns
Type Description
BigQueryResults

The result of the query.
Remarks

This method will only return when the query has completed.

Example

See BigQueryClient.GetQueryResults for an example using BigQueryClient.

GetQueryResultsAsync(GetQueryResultsOptions, CancellationToken)

public Task<BigQueryResults> GetQueryResultsAsync(GetQueryResultsOptions options = null, CancellationToken cancellationToken = default)

Asynchronously retrieves the result of this job, which must be a query job. This method just creates a JobReference and delegates to GetQueryResultsAsync(JobReference, GetQueryResultsOptions, CancellationToken).

Parameters
Name Description
options GetQueryResultsOptions

The options for the operation. May be null, in which case defaults will be supplied.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
TaskBigQueryResults

A task representing the asynchronous operation. When complete, the result is a BigQueryResults representation of the query.
Remarks

The task returned by this method will only complete when the query has completed.

Example

See BigQueryClient.GetQueryResultsAsync for an example using BigQueryClient.

PollUntilCompleted(GetJobOptions, PollSettings)

public BigQueryJob PollUntilCompleted(GetJobOptions options = null, PollSettings pollSettings = null)

Polls this job for completion, returning a new BigQueryJob object with the updated information. This method just creates a JobReference and delegates to PollJobUntilCompleted(JobReference, GetJobOptions, PollSettings).

Parameters
Name Description
options GetJobOptions

The options for the operation. May be null, in which case defaults will be supplied.
pollSettings PollSettings

The settings to control how often and long the job is fetched before timing out if it is still incomplete. May be null, in which case defaults will be supplied.
Returns
Type Description
BigQueryJob

The completed job.
Remarks

Note that this method does not modify the state of the object it is called on. Instead, a new object is returned. If you need to check that the job completed without errors, or access any other information, you need to use the return value of the method.

Example

See BigQueryClient.PollJobUntilCompleted for an example using BigQueryClient.

PollUntilCompletedAsync(GetJobOptions, PollSettings, CancellationToken)

public Task<BigQueryJob> PollUntilCompletedAsync(GetJobOptions options = null, PollSettings pollSettings = null, CancellationToken cancellationToken = default)

Asynchronously polls this job for completion. This method just creates a JobReference and delegates to PollJobUntilCompletedAsync(JobReference, GetJobOptions, PollSettings, CancellationToken).

Parameters
Name Description
options GetJobOptions

The options for the operation. May be null, in which case defaults will be supplied.
pollSettings PollSettings

The settings to control how often and long the job is fetched before timing out if it is still incomplete. May be null, in which case defaults will be supplied.
cancellationToken CancellationToken

The token to monitor for cancellation requests.
Returns
Type Description
TaskBigQueryJob

A task representing the asynchronous operation. When complete, the result is the completed job.
Example

See BigQueryClient.PollJobUntilCompleted for an example using BigQueryClient.

ThrowOnAnyError()

public BigQueryJob ThrowOnAnyError()

Throws an exception if the job has any errors, or returns this if the job has no errors so far. A job may have errors but still contain useful information, and may also contain errors before completing. If this method is called on a job that completed successfully but with errors, it will throw an exception. Use ThrowOnFatalError() to only throw an exception if a job has failed.

Returns
Type Description
BigQueryJob

this if the job has no errors.
Example 
BigQueryClient client = BigQueryClient.Create(projectId);

string sql = $"This is a broken query";
BigQueryJob query = client.CreateQueryJob(sql, parameters: null).PollUntilCompleted();
try
{
    // Usually this method is called in a chain. It returns the same job
    // if there are no errors.
    query = query.ThrowOnAnyError();
}
catch (GoogleApiException exception)
{
    foreach (var error in exception.Error.Errors)
    {
        Console.WriteLine($"Location: {error.Location}; Reason: {error.Reason}; Message: {error.Message}");
    }
}
Exceptions
Type Description
GoogleApiException

The job has errors. The Errors property corresponds to the errors reported in Errors.

ThrowOnFatalError()

public BigQueryJob ThrowOnFatalError()

Throws an exception if the job has failed. Returns this if the job has not failed, even if it contains errors. A job may have errors but still contain useful information, and may also contain errors before completing. Use ThrowOnAnyError() to throw an exception if any errors have been reported.

Returns
Type Description
BigQueryJob

this if the job has not completed unsuccessfully (either because it hasn't completed, or it has completed successfully, potentially with non-fatal errors).
Exceptions
Type Description
GoogleApiException

The job has failed. Within the Errors property, the first error is from the ErrorResult, and any others are from Errors.