Constructor

Table

new Table(instance, name)

Create a Table object to interact with a Cloud Bigtable table.

Parameter

instance

Instance

Name of the table.

name

string

Name of the table.

Example

const Bigtable = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');
const table = instance.table('prezzy');

Methods

create

create(options)

Create a table.

Parameter

options

Optional

object

See Instance#createTable.

Example

table.create(function(err, table, apiResponse) {
  if (!err) {
    // The table was created successfully.
  }
});

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

createFamily

createFamily(name, rule, callback)

Create a column family.

Optionally you can send garbage collection rules and when creating a family. Garbage collection executes opportunistically in the background, so it's possible for reads to return a cell even if it matches the active expression for its family.

Parameter

name

string

The name of column family.

rule

Optional

object

Garbage collection rule.

callback

function()

The callback function.

See also

Garbage Collection Proto Docs

Throws

error 

If a name is not provided.

Example

const Bigtable = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');
const table = instance.table('prezzy');

const callback = function(err, family, apiResponse) {
  // `family` is a Family object
};

const rule = {
  age: {
    seconds: 0,
    nanos: 5000
  },
  versions: 3,
  union: true
};

table.createFamily('follows', rule, callback);

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

createReadStream

createReadStream(options) returns stream

Get Row objects for the rows currently in your table as a readable object stream.

Parameter

options

Optional

object

Configuration object.

Returns

stream 

Example

const Bigtable = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');
const table = instance.table('prezzy');

table.createReadStream()
  .on('error', console.error)
  .on('data', function(row) {
    // `row` is a Row object.
  })
  .on('end', function() {
    // All rows retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing.
//-
table.createReadStream()
  .on('data', function(row) {
    this.end();
  });

//-
// Specify arbitrary keys for a non-contiguous set of rows.
// The total size of the keys must remain under 1MB, after encoding.
//-
table.createReadStream({
  keys: [
    'alincoln',
    'gwashington'
  ]
});

//-
// Scan for row keys that contain a specific prefix.
//-
table.createReadStream({
  prefix: 'gwash'
});

//-
// Specify a contiguous range of rows to read by supplying `start` and `end`
// keys.
//
// If the `start` key is omitted, it is interpreted as an empty string.
// If the `end` key is omitted, it is interpreted as infinity.
//-
table.createReadStream({
  start: 'alincoln',
  end: 'gwashington'
});

//-
// Specify multiple ranges.
//-
table.createReadStream({
  ranges: [{
    start: 'alincoln',
    end: 'gwashington'
  }, {
    start: 'tjefferson',
    end: 'jadams'
  }]
});

//-
// Apply a {@link Filter} to the contents of the specified rows.
//-
table.createReadStream({
  filter: [
    {
      column: 'gwashington'
    }, {
      value: 1
    }
  ]
});

delete

delete(callback)

Delete the table.

Parameter

callback

Optional

function()

The callback function.

Example

table.delete(function(err, apiResponse) {});

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

deleteRows

deleteRows(options, callback)

Delete all rows in the table, optionally corresponding to a particular prefix.

Parameter

options

Optional

object

Configuration object.

callback

function()

The callback function.

Example

const Bigtable = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');
const table = instance.table('prezzy');

//-
// You can supply a prefix to delete all corresponding rows.
//-
const callback = function(err, apiResponse) {
  if (!err) {
    // Rows successfully deleted.
  }
};

table.deleteRows({
  prefix: 'alincoln'
}, callback);

//-
// If you choose to omit the prefix, all rows in the table will be deleted.
//-
table.deleteRows(callback);

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

exists

exists(callback)

Check if a table exists.

Parameter

callback

function()

The callback function.

Example

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

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

family

family(name) returns Family

Get a reference to a Table Family.

Parameter

name

string

The family name.

Throws

error 

If a name is not provided.

Returns

Family 

Example

const family = table.family('my-family');

get

get(options)

Get a table if it exists.

You may optionally use this to "get or create" an object by providing an object with autoCreate set to true. Any extra configuration that is normally required for the create method must be contained within this object as well.

Parameter

options

Optional

object

Configuration object.

Example

table.get(function(err, table, apiResponse) {
  // The `table` data has been populated.
});

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

getFamilies

getFamilies(callback)

Get Family objects for all the column familes in your table.

Parameter

callback

function()

The callback function.

Example

const Bigtable = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');
const table = instance.table('prezzy');

table.getFamilies(function(err, families, apiResponse) {
  // `families` is an array of Family objects.
});

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

getMetadata

getMetadata(options, callback)

Get the table's metadata.

Parameter

options

Optional

object

Table request options.

callback

Optional

function()

The callback function.

Example

const Bigtable = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');
const table = instance.table('prezzy');

table.getMetadata(function(err, metadata, apiResponse) {});

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

getRows

getRows(options, callback)

Get Row objects for the rows currently in your table.

This method is not recommended for large datasets as it will buffer all rows before returning the results. Instead we recommend using the streaming API via Table#createReadStream.

Parameter

options

Optional

object

Configuration object. See Table#createReadStream for a complete list of options.

callback

function()

The callback function.

Example

const Bigtable = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');
const table = instance.table('prezzy');

table.getRows(function(err, rows) {
  if (!err) {
    // `rows` is an array of Row objects.
  }
});

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

insert

insert(entries, callback)

Insert or update rows in your table. It should be noted that gRPC only allows you to send payloads that are less than or equal to 4MB. If you're inserting more than that you may need to send smaller individual requests.

Parameter

entries

(object or Array of object)

List of entries to be inserted. See Table#mutate.

callback

function()

The callback function.

Example

const Bigtable = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');
const table = instance.table('prezzy');

const callback = function(err) {
  if (err) {
    // An API error or partial failure occurred.

    if (err.name === 'PartialFailureError') {
      // err.errors[].code = 'Response code'
      // err.errors[].message = 'Error message'
      // err.errors[].entry = The original entry
    }
  }
};

const entries = [
 {
    key: 'alincoln',
    data: {
      follows: {
        gwashington: 1
      }
    }
  }
];

table.insert(entries, callback);

//-
// By default whenever you insert new data, the server will capture a
// timestamp of when your data was inserted. It's possible to provide a
// date object to be used instead.
//-
const entries = [
  {
    key: 'gwashington',
    data: {
      follows: {
        jadams: {
          value: 1,
          timestamp: new Date('March 22, 2016')
        }
      }
    }
  }
];

table.insert(entries, callback);


//-
// If the callback is omitted, we'll return a Promise.
//-
table.insert(entries).then(function() {
  // All requested inserts have been processed.
});
//-

mutate

mutate(entries, callback)

Apply a set of changes to be atomically applied to the specified row(s). Mutations are applied in order, meaning that earlier mutations can be masked by later ones.

Parameter

entries

(object or Array of object)

List of entities to be inserted or deleted.

callback

function()

The callback function.

Example

const Bigtable = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');
const table = instance.table('prezzy');

//-
// Insert entities. See {@link Table#insert}.
//-
const callback = function(err) {
  if (err) {
    // An API error or partial failure occurred.

    if (err.name === 'PartialFailureError') {
      // err.errors[].code = 'Response code'
      // err.errors[].message = 'Error message'
      // err.errors[].entry = The original entry
    }
  }
};

const entries = [
  {
    method: 'insert',
    key: 'gwashington',
    data: {
      follows: {
        jadams: 1
      }
    }
  }
];

table.mutate(entries, callback);

//-
// Delete entities. See {@link Row#deleteCells}.
//-
const entries = [
  {
    method: 'delete',
    key: 'gwashington'
  }
];

table.mutate(entries, callback);

//-
// Delete specific columns within a row.
//-
const entries = [
  {
    method: 'delete',
    key: 'gwashington',
    data: [
      'follows:jadams'
    ]
  }
];

table.mutate(entries, callback);

//-
// Mix and match mutations. This must contain at least one entry and at
// most 100,000.
//-
const entries = [
  {
    method: 'insert',
    key: 'alincoln',
    data: {
      follows: {
        gwashington: 1
      }
    }
  }, {
    method: 'delete',
    key: 'jadams',
    data: [
      'follows:gwashington'
    ]
  }
];

table.mutate(entries, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
table.mutate(entries).then(function() {
  // All requested mutations have been processed.
});

row

row(key) returns Row

Get a reference to a table row.

Parameter

key

string

The row key.

Throws

error 

If a key is not provided.

Returns

Row 

Example

var row = table.row('lincoln');

sampleRowKeys

sampleRowKeys(callback)

Returns a sample of row keys in the table. The returned row keys will delimit contigous sections of the table of approximately equal size, which can be used to break up the data for distributed tasks like mapreduces.

Parameter

callback

Optional

function()

The callback function.

Example

table.sampleRowKeys(function(err, keys) {
  // keys = [
  //   {
  //     key: '',
  //     offset: '805306368'
  //   },
  //   ...
  // ]
});

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

sampleRowKeysStream

sampleRowKeysStream() returns stream

Returns a sample of row keys in the table as a readable object stream.

See Table#sampleRowKeys for more details.

Returns

stream 

Example

table.sampleRowKeysStream()
  .on('error', console.error)
  .on('data', function(key) {
    // Do something with the `key` object.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing.
//-
table.sampleRowKeysStream()
  .on('data', function(key) {
    this.end();
  });