Google BigQuery v2 API - Class BigQueryJob (3.8.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

Inherited Members

object.GetHashCode()

object.GetType()

object.ToString()

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.