Job

Job

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.

Constructor

new Job(bigQuery, id, optionsopt)

Parameters:
Name Type Attributes Description
bigQuery BigQuery

BigQuery instance.
id string

The ID of the job.
options object <optional>

Configuration object.

Properties
Name Type Attributes Description
location string <optional>

The geographic location of the job. Required except for US and EU.
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();

Members

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'));

Methods

cancel(callbackopt) → {Promise}

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

Parameters:
Name Type Attributes Description
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
apiResponse object

The full API response.
Returns:
Type Description
Promise
See:
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];
});

exists(callbackopt) → {Promise}

Check if the job exists.

Parameters:
Name Type Attributes Description
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
exists boolean

Whether the job exists or not.
Returns:
Type Description
Promise
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];
});

get(callbackopt) → {Promise}

Get a job if it exists.

Parameters:
Name Type Attributes Description
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
job Job

The job.
Returns:
Type Description
Promise
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];
});

getMetadata(callbackopt) → {Promise}

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

Parameters:
Name Type Attributes Description
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
metadata object

The metadata of the job.
apiResponse object

The full API response.
Returns:
Type Description
Promise
See:
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];
});

getQueryResults(optionsopt, callbackopt) → {Promise}

Get the results of a job.

Parameters:
Name Type Attributes Description
options object <optional>

Configuration object.

Properties
Name Type Attributes Default Description
autoPaginate boolean <optional>
 true

Have pagination handled automatically.
maxApiCalls number <optional>

Maximum number of API calls to make.
maxResults number <optional>

Maximum number of results to read.
pageToken string <optional>

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 <optional>

Zero-based index of the starting row.
timeoutMs number <optional>

How long to wait for the query to complete, in milliseconds, before returning. Default is 10 seconds. If the timeout passes before the job completes, an error will be returned and the 'jobComplete' field in the response will be false.
wrapIntegers boolean | IntegerTypeCastOptions <optional>
 false

Wrap values of 'INT64' type in BigQueryInt objects. If a boolean, this will wrap values in BigQueryInt objects. If an object, this will return a value returned by wrapIntegers.integerTypeCastFunction.
callback QueryResultsCallback | ManualQueryResultsCallback <optional>

The callback function. If autoPaginate is set to false a ManualQueryResultsCallback should be used.
Returns:
Type Description
Promise
See:
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];
});