class

Job

Source: job.js:94

Job objects are returned from various places in the BigQuery API:

They can be used to check the status of a running job or fetching the results of a previously-executed one.

Property

getQueryResultsStream

Methods

cancel([callback])
exists([callback])

get([callback])
getMetadata([callback])

getQueryResults([options][, callback])

new Job(bigQuery, id[, options])

Example

const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

const job = bigquery.job('job-id');

//-
// All jobs are event emitters. The status of each job is polled
// continuously, starting only after you register a "complete" listener.
//-
job.on('complete', (metadata) => {
  // The job is complete.
});

//-
// Be sure to register an error handler as well to catch any issues which
// impeded the job.
//-
job.on('error', (err) => {
  // An error occurred during the job.
});

//-
// To force the Job object to stop polling for updates, simply remove any
// "complete" listeners you've registered.
//
// The easiest way to do this is with `removeAllListeners()`.
//-
job.removeAllListeners();

Parameters

Name Type Optional Description

bigQuery

BigQuery instance.

The ID of the job.

options

Yes

Configuration object.

Values in options have the following properties:

Name	Type	Optional	Description
location		Yes	The geographic location of the job. Required except for US and EU.

Property

getQueryResultsStream

Get the results of a job as a readable object stream.

Example

const through2 = require('through2');
const fs = require('fs');
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

const job = bigquery.job('job-id');

job.getQueryResultsStream()
  .pipe(through2.obj(function (row, enc, next) {
    this.push(JSON.stringify(row) + '\n');
    next();
  }))
  .pipe(fs.createWriteStream('./test/testdata/testfile.json'));

Parameter

Name	Type	Optional	Description
options	object		Configuration object. See Job#getQueryResults for a complete list of options.

Returns: stream

Methods

cancel([callback]) → Promise

Cancel a job. Use Job#getMetadata to see if the cancel completes successfully. See an example implementation below.

Example

const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

const job = bigquery.job('job-id');

job.cancel((err, apiResponse) =>{
  // Check to see if the job completes successfully.
  job.on('error', (err) => {});
  job.on('complete', (metadata) => {});
});

//-
// If the callback is omitted, we'll return a Promise.
//-
job.cancel().then((data) => {
  const apiResponse = data[0];
});

Parameters

Name Type Optional Description

callback

function()

Yes

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can be null.

apiResponse

object

The full API response.

See also: Jobs: get API Documentation
Returns: Promise

exists([callback]) → Promise

Check if the job exists.

Example

const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

const job = bigquery.job('job-id');

job.exists((err, exists) => {});

//-
// If the callback is omitted, we'll return a Promise.
//-
job.exists().then((data) => {
  const exists = data[0];
});

Parameters

Name Type Optional Description

callback

function()

Yes

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can be null.

exists

boolean

Whether the job exists or not.

Returns: Promise

get([callback]) → Promise

Get a job if it exists.

Example

const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

const job = bigquery.job('job-id');

job.get((err, job, apiResponse) => {
  if (!err) {
    // `job.metadata` has been populated.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
job.get().then((data) => {
  const job = data[0];
  const apiResponse = data[1];
});

Parameters

Name Type Optional Description

callback

function()

Yes

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can be null.

job

Job

The job.

Returns: Promise

getMetadata([callback]) → Promise

Get the metadata of the job. This will mostly be useful for checking the status of a previously-run job.

Example

const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

const job = bigquery.job('id');
job.getMetadata((err, metadata, apiResponse) => {});

//-
// If the callback is omitted, we'll return a Promise.
//-
job.getMetadata().then((data) => {
  const metadata = data[0];
  const apiResponse = data[1];
});

Parameters

Name Type Optional Description

callback

function()

Yes

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can be null.

metadata

object

The metadata of the job.

apiResponse

object

The full API response.

See also: Jobs: get API Documentation
Returns: Promise

getQueryResults([options][, callback]) → Promise

Get the results of a job.

Example

const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

const job = bigquery.job('job-id');

//-
// Get all of the results of a query.
//-
job.getQueryResults((err, rows) => {
  if (!err) {
    // rows is an array of results.
  }
});

//-
// Customize the results you want to fetch.
//-
job.getQueryResults({
  maxResults: 100
}, (err, rows) => {});

//-
// To control how many API requests are made and page through the results
// manually, set `autoPaginate` to `false`.
//-
function manualPaginationCallback(err, rows, nextQuery, apiResponse) {
  if (nextQuery) {
    // More results exist.
    job.getQueryResults(nextQuery, manualPaginationCallback);
  }
}

job.getQueryResults({
  autoPaginate: false
}, manualPaginationCallback);

//-
// If the callback is omitted, we'll return a Promise.
//-
job.getQueryResults().then((data) => {
  const rows = data[0];
});

Parameters

Name Type Optional Description

options

object

Yes

Configuration object.

Values in options have the following properties:

Name	Type	Optional	Description
autoPaginate	boolean	Yes	Have pagination handled automatically. Defaults to `true`.
maxApiCalls	number	Yes	Maximum number of API calls to make.
maxResults	number	Yes	Maximum number of results to read.
pageToken	string	Yes	Page token, returned by a previous call, to request the next page of results. Note: This is automatically added to the `nextQuery` argument of your callback.
startIndex	number	Yes	Zero-based index of the starting row.
timeoutMs	number	Yes	How long to wait for the query to complete, in milliseconds, before returning. Default is to return immediately. If the timeout passes before the job completes, the request will fail with a `TIMEOUT` error.

callback

(QueryResultsCallback or ManualQueryResultsCallback)

Yes

The callback function. If autoPaginate is set to false a ManualQueryResultsCallback should be used.

See also: Jobs: getQueryResults API Documentation
Returns: Promise