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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_create_instance

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_create_app_profile

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_create_cluster

createExecuteQueryStream(preparedStatementopt, optsopt) → {ExecuteQueryStreamWithMetadata}

Execute a SQL query on an instance.

Parameters:
Name Type Attributes Description
preparedStatement PreparedStatement <optional>

SQL query to execute. Parameters can be specified using @name notation.

opts object <optional>

Configuration object.

Properties
Name Type Attributes Description
parameters object <optional>

Object mapping names of parameters used in the query to JS values.

retryOptions object <optional>

Retry options used for executing the query. Note that the only values used are:

  • retryOptions.retry.retryCodes
  • retryOptions.retry.backoffSettings.maxRetries
  • retryOptions.retry.backoffSettings.totalTimeoutMillis
  • retryOptions.retry.backoffSettings.maxRetryDelayMillis
  • retryOptions.retry.backoffSettings.retryDelayMultiplier
  • retryOptions.retry.backoffSettings.initialRetryDelayMillis
Returns:
Type Description
ExecuteQueryStreamWithMetadata
Example

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_create_query_stream

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_create_table

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

include:samples/api-reference-doc-snippets/backups.restore.js

region_tag:bigtable_api_restore_backup

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_del_instance

executeQuery(preparedStatementopt, nullable, optionsopt, nullable, callback)

Execute a SQL query on an instance.

Parameters:
Name Type Attributes Description
preparedStatement PreparedStatement <optional>
<nullable>

PreparedStatement object representing a query to execute.

options object <optional>
<nullable>

Configuration object. See Instance#createExecuteQueryStream for a complete list of options.

callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.

rows Array.<QueryResultRow> <nullable>

List of rows.

metadata SqlTypes.ResultSetMetadata <nullable>

Metadata for the response.

Example

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_execute_query

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_exists_instance

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_get_instance

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_get_app_profiles

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

include:samples/api-reference-doc-snippets/backups.list.js

region_tag:bigtable_api_list_backups

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_get_clusters

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_get_instance_Iam_policy

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_get_instance_metadata

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_get_tables

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();
  });
```

prepareStatement(queryopt, nullable, callback)

Prepare an SQL query to be executed on an instance.

Parameters:
Name Type Attributes Description
query string <optional>
<nullable>

PreparedStatement object representing a query to execute.

opts.query string <optional>

Query string for which we want to construct the preparedStatement object.

opts.parameterTypes object <optional>

Object mapping names of parameters to their types. Type hints should be constructed using factory functions such as Int64

opts.retryOptions CallOptions <optional>

gax's CallOptions wich are passed straight to gax. The same retry options are also used when automatically refreshing the PreparedStatement.

callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.

preparedStatement PreparedStatement <nullable>

The preparedStatement object used to perform the executeQuery operation.

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_set_instance_Iam_policy

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_set_meta_data

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

include:samples/api-reference-doc-snippets/instance.js

region_tag:bigtable_api_test_instance_Iam_permissions

view(tableName, viewName)

Gets an Authorized View object for making authorized view grpc calls.

Parameters:
Name Type Description
tableName string

The name for the Table

viewName string

The name for the Authorized view