Constructor

Job

new Job(bigQuery, id)

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.

Parameter

bigQuery

BigQuery

BigQuery instance.

id

string

The ID of the job.

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', function(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', function(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();

Property

getQueryResultsStream

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

Parameter

options

object

Configuration object. See Job#getQueryResults for a complete list of options.

Returns

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

cancel(callback) returns Promise

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

Parameter

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

apiResponse

object

The full API response.

See also

Jobs: get API Documentation

Returns

Promise 

Example

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

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

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

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

exists

exists(callback) returns Promise

Check if the job exists.

Parameter

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

exists

boolean

Whether the job exists or not.

Returns

Promise 

Example

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

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

job.exists(function(err, exists) {});

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

get

get(callback) returns Promise

Get a job if it exists.

Parameter

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

job

Job

The job.

Returns

Promise 

Example

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

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

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

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

getMetadata

getMetadata(callback) returns Promise

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

Parameter

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

metadata

object

The metadata of the job.

apiResponse

object

The full API response.

See also

Jobs: get API Documentation

Returns

Promise 

Example

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

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

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

getQueryResults

getQueryResults(options, callback) returns Promise

Get the results of a job.

Parameter

options

Optional

object

Configuration object.

Values in options have the following properties:

Parameter

autoPaginate

Optional

boolean

Have pagination handled automatically.

maxApiCalls

Optional

number

Maximum number of API calls to make.

maxResults

Optional

number

Maximum number of results to read.

pageToken

Optional

string

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

Optional

number

Zero-based index of the starting row.

timeoutMs

Optional

number

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

Optional

(QueryResultsCallback or ManualQueryResultsCallback)

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

See also

Jobs: getQueryResults API Documentation

Returns

Promise 

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(function(err, rows) {
  if (!err) {
    // rows is an array of results.
  }
});

//-
// Customize the results you want to fetch.
//-
job.getQueryResults({
  maxResults: 100
}, function(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(function(data) {
  var rows = data[0];
});

setMetadata

setMetadata(metadata, callback) returns Promise

Set the metadata for this job. This can be useful for updating job labels.

Parameter

metadata

object

Metadata to save on the Job.

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

apiResponse

object

The full API response.

See also

Jobs: patch API Documentation

Returns

Promise 

Example

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

const metadata = {
  configuration: {
    labels: {
      foo: 'bar'
    }
  }
};

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

job.setMetadata(metadata, function(err, apiResponse) {});

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