Instance

Instance

Create an Instance object to interact with a Cloud Bigtable instance.

Constructor

new Instance(bigtable, id)

Parameters:
Name Type Description
bigtable Bigtable

The parent Bigtable object of this instance.
id string

Id of the instance.
Example
```
const {Bigtable} = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');
```

Methods

appProfile(name) → {AppProfile}

Get a reference to a Bigtable App Profile.

Parameters:
Name Type Description
name string

The name of the app profile.
Returns:
Type Description
AppProfile

cluster(id) → {Cluster}

Get a reference to a Bigtable Cluster.

Parameters:
Name Type Description
id string

The id of the cluster.
Returns:
Type Description
Cluster

create(options, callback)

Create an instance.

Parameters:
Name Type Description
options object

See Bigtable#createInstance.

Properties
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
instance Instance

The newly created instance.
operation Operation

An operation object that can be used to check the status of the request.
apiResponse object

The full API response.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    // options for a PRODUCTION Instance
    // const options = {
    //   clusters: [
    //     {
    //       id: clusterId,
    //       nodes: 3,
    //       location: 'us-central1-f',
    //       storage: 'ssd',
    //     },
    //   ],
    //   type: 'PRODUCTION', // Optional as default type is PRODUCTION
    // };

    // options for a DEVELOPMENT Instance
    const options = {
      clusters: [
        {
          id: clusterId,
          location: 'us-central1-f',
          storage: 'hdd',
        },
      ],
      type: 'DEVELOPMENT',
    };

    // creates a new Instance
    instance
      .create(options)
      .then(result => {
        const newInstance = result[0];
        // let operations = result[1];
        // let apiResponse = result[2];
      })
      .catch(err => {
        // Handle the error.
      });

createAppProfile(id, options, callback)

Create an app profile.

Parameters:
Name Type Description
id string

The name to be used when referring to the new app profile within its instance.
options object

AppProfile creation options.

Properties
Name Type Attributes Description
routing 'any' | Cluster

The routing policy for all read/write requests which use this app profile. This can be either the string 'any' or a cluster of an instance. This value is required when creating the app profile and optional when setting the metadata.
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
allowTransactionalWrites boolean <optional>

Whether or not CheckAndMutateRow and ReadModifyWriteRow requests are allowed by this app profile. It is unsafe to send these requests to the same table/row/column in multiple clusters. This is only used when the routing value is a cluster.
description string <optional>

The long form description of the use case for this AppProfile.
ignoreWarnings string <optional>

Whether to ignore safety checks when creating the app profile
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
appProfile Cluster

The newly created app profile.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    const cluster = instance.cluster(clusterId);

    const options = {
      routing: cluster,
      allowTransactionalWrites: true,
      ignoreWarnings: true,
    };

    instance.createAppProfile(appProfileId, options, (err, appProfile) => {
      if (err) {
        // Handle the error.
        return callback(err);
      }
      return callback(appProfile);
    });

createCluster(id, options, callback)

Create a cluster.

Parameters:
Name Type Description
id string

The id to be used when referring to the new cluster within its instance.
options object

Cluster creation options.

Properties
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
encryption object <optional>

CMEK configuration options.

Properties
Name Type Description
kmsKeyName string

The KMS key name.
key string <optional>

Alias for options.encryption.kmsKeyName.
location string

The location where this cluster's nodes and storage reside. For best performance clients should be located as as close as possible to this cluster. Currently only zones are supported.
nodes number

The number of nodes allocated to this cluster. More nodes enable higher throughput and more consistent performance.
storage string <optional>

The type of storage used by this cluster to serve its parent instance's tables. Options are 'hdd' or 'ssd'.
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
cluster Cluster

The newly created cluster.
operation Operation

An operation object that can be used to check the status of the request.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    // const options = {
    //   location: 'us-central1-b',
    //   nodes: 3,
    //   storage: 'ssd',
    // };
    const options = {
      location: 'us-central1-b',
      storage: 'hdd',
    };
    instance
      .createCluster(clusterId, options)
      .then(result => {
        const newCluster = result[0];
        // const operations = result[1];
        // const apiResponse = result[2];
      })
      .catch(err => {
        // Handle the error.
      });

createTable(id, optionsopt, callback)

Create a table on your Bigtable instance.

Parameters:
Name Type Attributes Description
id string

Unique identifier of the table.
options object <optional>

Table creation options.

Properties
Name Type Attributes Description
families object | Array.<string> <optional>

Column families to be created within the table.
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
splits Array.<string> <optional>

Initial split keys.
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
table Table

The newly created table.
apiResponse object

The full API response.
See:
Throws:

If a id is not provided.

Type
error
Example
    table
      .create()
      .then(result => {
        const table = result[0];
        // let apiResponse = result[1];
      })
      .catch(err => {
        // Handle the error.
      });

createTableFromBackup(config, cbopt) → {void|Promise.<RestoreTableResponse>}

Create a new table by restoring from a completed backup.

The new table must be in the same instance as the instance containing the backup. The returned table long-running operation can be used to track the progress of the operation, and to cancel it.

Parameters:
Name Type Attributes Description
config CreateTableFromBackupConfig

Configuration object.

Properties
Name Type Attributes Description
backup Backup | string

The name of the backup from which to restore of the form projects/<project>/instances/<instance>/clusters/<cluster>/backups/<backup>, or a Backup instance.
table string

The id of the table to create and restore to.
gaxOptions CallOptions <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
cb RestoreTableCallback <optional>
Returns:
Type Description
void | Promise.<RestoreTableResponse>
Example
  const {Bigtable} = require('@google-cloud/bigtable');
  const bigtable = new Bigtable();

  async function restoreBackup() {
    /**
     * TODO(developer): Uncomment these variables before running the sample.
     */
    // const instanceId = 'YOUR_INSTANCE_ID';
    // const tableId = 'YOUR_TABLE_ID';
    // const backupId = 'YOUR_BACKUP_ID';
    const instance = bigtable.instance(instanceId);

    // Restore a table to an instance.
    const [table, operation] = await instance.createTableFromBackup({
      table: tableId,
      backup: backupId,
    });

    await operation.promise();
    console.log(`Table restored to ${table.id} successfully.`);
  }

  await restoreBackup();

delete(gaxOptionsopt, callbackopt)

Delete the instance.

Parameters:
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
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.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    instance
      .delete()
      .then(result => {
        const apiResponse = result[0];
      })
      .catch(err => {
        // Handle the error.
      });

exists(gaxOptionsopt, callback)

Check if an instance exists.

Parameters:
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
exists boolean

Whether the instance exists or not.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    instance
      .exists()
      .then(result => {
        const exists = result[0];
      })
      .catch(err => {
        // Handle the error.
      });

get(gaxOptionsopt, callback)

Get an instance if it exists.

Parameters:
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
callback function

The callback function.

Properties
Name Type Attributes Description
error error <nullable>

An error returned while making this request.
instance Instance

The Instance object.
apiResponse object

The resource as it exists in the API.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    instance
      .get()
      .then(result => {
        const instance = result[0];
        // const apiResponse = result[1];
      })
      .catch(err => {
        // Handle the error.
      });

getAppProfiles(gaxOptionsopt, callback)

Get App Profile objects for this instance.

Parameters:
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
callback function

The callback function.

Properties
Name Type Attributes Description
error error <nullable>

An error returned while making this request.
appProfiles Array.<AppProfile>

List of all AppProfiles.
apiResponse object

The full API response.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    instance
      .getAppProfiles()
      .then(result => {
        const appProfiles = result[0];
      })
      .catch(err => {
        // Handle the error.
      });

getAppProfilesStream(gaxOptionsopt) → {stream}

Get AppProfile objects for all the App Profiles in your Cloud Bigtable instance as a readable object stream.

Parameters:
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html. Instance#getAppProfiles for a complete list of options.
Returns:
Type Description
stream
Example
```
const {Bigtable} = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');

instance.getAppProfilesStream()
  .on('error', console.error)
  .on('data', function(appProfile) {
    // appProfile is a AppProfile object.
  })
  .on('end', () => {
    // All appProfiles retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
instance.getAppProfilesStream()
  .on('data', function(appProfile) {
    this.end();
  });
```

getBackups(optionsOrCallbackopt, callbackopt) → {void|Promise.<ListBackupsResponse>}

Get Cloud Bigtable Backup instances within this instance. This returns both completed and pending backups.

Parameters:
Name Type Attributes Description
optionsOrCallback GetBackupsOptions | GetBackupsCallback <optional>
callback GetBackupsResponse <optional>

The callback function.

Properties
Name Type Attributes Description
error error <nullable>

An error returned while making this request.
backups Array.<Backup>

All matching Backup instances.
apiResponse object

The full API response.
Returns:
Type Description
void | Promise.<ListBackupsResponse>
Example
  const {Bigtable} = require('@google-cloud/bigtable');
  const bigtable = new Bigtable();

  async function listBackups() {
    /**
     * TODO(developer): Uncomment these variables before running the sample.
     */
    // const instanceId = 'YOUR_INSTANCE_ID';
    // const tableId = 'YOUR_TABLE_ID';
    // const clusterId = 'YOUR_CLUSTER_ID';
    const instance = bigtable.instance(instanceId);
    const table = instance.table(tableId);
    const cluster = table.cluster(clusterId);

    const [backupsFromInstance] = await instance.listBackups();
    console.log(
      `${backupsFromInstance.length} backups returned from the instance.`
    );

    const [backupsFromCluster] = await cluster.listBackups();
    console.log(
      `${backupsFromCluster.length} backups returned from the cluster.`
    );
  }

  await listBackups();

getBackupsStream(optionsopt) → {ReadableStream.<Backup>}

Get Cloud Bigtable Backup instances within this instance. This returns both completed and pending backups as a readable stream.

Parameters:
Name Type Attributes Description
options GetBackupsOptions <optional>

Configuration object. See Instance#getBackups for a complete list of options.
Returns:
Type Description
ReadableStream.<Backup>
Example
```
const {Bigtable} = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');

instance.getBackupsStream()
  .on('error', console.error)
  .on('data', function(backup) {
    // backup is a Backup object.
  })
  .on('end', () => {
    // All backups retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
instance.getBackupsStream()
  .on('data', function(backup) {
    this.end();
  });
```

getClusters(gaxOptionsopt, callback)

Get Cluster objects for all of your clusters.

Parameters:
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
callback function

The callback function.

Properties
Name Type Attributes Description
error error <nullable>

An error returned while making this request.
clusters Array.<Cluster>

List of all Clusters.
apiResponse object

The full API response.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    instance
      .getClusters()
      .then(result => {
        const clusters = result[0];
      })
      .catch(err => {
        // Handle the error.
      });

getIamPolicy(optionsopt, callbackopt, policy)

Parameters:
Name Type Attributes Description
options object <optional>

Configuration object.

Properties
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
requestedPolicyVersion number <optional>

The policy format version to be returned. Valid values are 0, 1, and 3. Requests specifying an invalid value will be rejected. Requests for policies with any conditional bindings must specify version 3. Policies without any conditional bindings may specify any valid value or leave the field unset.
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
error error <nullable>

An error returned while making this request.
policy Policy

The policy.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    instance
      .getIamPolicy()
      .then(result => {
        const policy = result[0];
      })
      .catch(err => {
        // Handle the error.
      });

getMetadata(gaxOptionsopt, callback)

Get the instance metadata.

Parameters:
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
metadata object

The metadata.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    instance
      .getMetadata()
      .then(result => {
        const metaData = result[0];
      })
      .catch(err => {
        // Handle the error.
      });

getTables(optionsopt, callback)

Get Table objects for all the tables in your Cloud Bigtable instance.

Parameters:
Name Type Attributes Description
options object <optional>

Query object.

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

Have pagination handled automatically.
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
maxApiCalls number <optional>

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

Maximum number of items to return.
pageToken string <optional>

A previously-returned page token representing part of a larger set of results to view.
view string <optional>

View over the table's fields. Possible options are 'name', 'schema' or 'full'. Default: 'name'.
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
tables Array.<Table>

List of all Table objects.These objects contains only table name & id but is not a complete representation of a table.
apiResponse object

The full API response.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    // To control how many API requests are made and page through the results
    // manually, set `autoPaginate` to false.
    const options = {
      autoPaginate: false,
    };
    // const options = {
    //   autoPaginate: true
    // };

    instance
      .getTables(options)
      .then(result => {
        const tables = result[0];
      })
      .catch(err => {
        // Handle the error.
      });

getTablesStream(optionsopt) → {stream}

Get Table objects for all the tables in your Cloud Bigtable instance as a readable object stream.

Parameters:
Name Type Attributes Description
options object <optional>

Query object. See Instance#getTables for a complete list of options.
Returns:
Type Description
stream
Example
```
const {Bigtable} = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');

instance.getTablesStream()
  .on('error', console.error)
  .on('data', function(table) {
    // table is a Table object.
  })
  .on('end', () => {
    // All tables retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
instance.getTablesStream()
  .on('data', function(table) {
    this.end();
  });
```

setIamPolicy(gaxOptionsopt, callbackopt, policy)

Parameters:
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
error error <nullable>

An error returned while making this request.
policy Policy

The policy.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    const policy = {
      bindings: [
        {
          role: 'roles/bigtable.viewer',
          members: ['user:mike@example.com', 'group:admins@example.com'],
        },
      ],
    };

    instance
      .setIamPolicy(policy)
      .then(result => {
        const setPolicy = result[0];
      })
      .catch(err => {
        // Handle the error
      });

setMetadata(metadata, gaxOptionsopt, callback)

Set the instance metadata.

Parameters:
Name Type Attributes Description
metadata object

Metadata object.

Properties
Name Type Description
displayName string

The descriptive name for this instance as it appears in UIs. It can be changed at any time, but should be kept globally unique to avoid confusion.
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
apiResponse object

The full API response.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    const metadata = {
      displayName: 'updated-name',
    };

    instance
      .setMetadata(metadata)
      .then(result => {
        const apiResponse = result[0];
      })
      .catch(err => {
        // Handle the error.
      });

table(id) → {Table}

Get a reference to a Bigtable table.

Parameters:
Name Type Description
id string

Unique identifier of the table.
Returns:
Type Description
Table
Example
```
const {Bigtable} = require('@google-cloud/bigtable');
const bigtable = new Bigtable();
const instance = bigtable.instance('my-instance');
const table = instance.table('presidents');
```

testIamPermissions(permissions, gaxOptionsopt, callbackopt, permissions)

Parameters:
Name Type Attributes Description
permissions string | Array.<string>

The permission(s) to test for.
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
error error <nullable>

An error returned while making this request.
permissions Array.<string>

A subset of permissions that the caller is allowed.
Example
    const {Bigtable} = require('@google-cloud/bigtable');
    const bigtable = new Bigtable();
    const instance = bigtable.instance(instanceId);

    const permissions = ['bigtable.tables.get', 'bigtable.tables.readRows'];
    instance
      .testIamPermissions(permissions)
      .then(result => {
        const grantedPermissions = result[0];
      })
      .catch(err => {
        // Handle the error
      });