Table

Table

Create a Table object to interact with a table in a Cloud Spanner database.

Constructor

new Table(database, name)

Parameters:
Name Type Description
database Database

Database instance.

name string

Name of the table.

Source:
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');
const table = database.table('my-table');

Members

database :Database

The Database instance of this Table instance.

Source:

name :string

The name of this table.

Source:

Methods

create(schema, callbackopt) → {Promise.<CreateTableResponse>}

Create a table.

Parameters:
Name Type Attributes Description
schema string

See Database#createTable.

callback CreateTableCallback <optional>

Callback function.

Source:
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');
const table = database.table('Singers');

const schema =
  'CREATE TABLE Singers (' +
  '  SingerId INT64 NOT NULL,' +
  '  FirstName STRING(1024),' +
  '  LastName STRING(1024),' +
  '  SingerInfo BYTES(MAX),' +
  ') PRIMARY KEY(SingerId)';

table.create(schema, function(err, table, operation, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  operation
    .on('error', function(err) {})
    .on('complete', function() {
      // Table created successfully.
    });
});

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

    return operation.promise();
  })
  .then(function() {
    // Table created successfully.
  });

createReadStream(query, optionsopt) → {ReadableStream}

Create a readable object stream to receive rows from the database using key lookups and scans.

Parameters:
Name Type Attributes Description
query ReadRequest

Configuration object. See official ReadRequest. API documentation.

options TimestampBounds <optional>

Transaction options.

Source:
See:
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');
const table = database.table('Singers');

table.createReadStream({
    keys: ['1'],
    columns: ['SingerId', 'name']
  })
  .on('error', function(err) {})
  .on('data', function(row) {
    // row = {
    //   SingerId: '1',
    //   Name: 'Eddie Wilson'
    // }
  })
  .on('end', function() {
    // All results retrieved.
  });

//-
// Provide an array for `query.keys` to read with a composite key.
//-
const query = {
  keys: [
    [
      'Id1',
      'Name1'
    ],
    [
      'Id2',
      'Name2'
    ]
  ],
  // ...
};

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
table.createReadStream({
    keys: ['1'],
    columns: ['SingerId', 'name']
  })
  .on('data', function(row) {
    this.end();
  });

delete(callbackopt) → {Promise.<LongRunningOperationResponse>}

Delete the table. Not to be confused with Table#deleteRows.

Wrapper around Database#updateSchema.

Parameters:
Name Type Attributes Description
callback LongRunningOperationCallback <optional>

Callback function.

Source:
See:
Throws:

If any arguments are passed in.

Type
TypeError
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');
const table = database.table('Singers');

table.delete(function(err, operation, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  operation
    .on('error', function(err) {})
    .on('complete', function() {
      // Table deleted successfully.
    });
});

//-
// If the callback is omitted, we'll return a Promise.
//-
table.delete()
  .then(function(data) {
    const operation = data[0];
    return operation.promise();
  })
  .then(function() {
    // Table deleted successfully.
  });

deleteRows(keys, callbackopt) → {Promise.<BasicResponse>}

Delete rows from this table.

Parameters:
Name Type Attributes Description
keys array

The keys for the rows to delete. If using a composite key, provide an array within this array. See the example below.

callback BasicCallback <optional>

Callback function.

Source:
See:
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');
const table = database.table('Singers');

const keys = ['Id1', 'Id2', 'Id3'];

table.deleteRows(keys, function(err, apiResponse) {});

//-
// Provide an array for `keys` to delete rows with a composite key.
//-
const keys = [
  [
    'Id1',
    'Name1'
  ],
  [
    'Id2',
    'Name2'
  ]
];

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

drop(callbackopt) → {Promise.<LongRunningOperationResponse>}

Drop the table.

Parameters:
Name Type Attributes Description
callback LongRunningOperationCallback <optional>

Callback function.

Source:
See:
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');
const table = database.table('Singers');

table.drop(function(err, operation, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  operation
    .on('error', function(err) {})
    .on('complete', function() {
      // Table dropped successfully.
    });
});

//-
// If the callback is omitted, we'll return a Promise.
//-
table.drop()
  .then(function(data) {
    const operation = data[0];
    return operation.promise();
  })
  .then(function() {
    // Table dropped successfully.
  });

insert(rows, callbackopt) → {Promise.<BasicResponse>}

Insert rows of data into this table.

Parameters:
Name Type Attributes Description
rows object | Array.<object>

A map of names to values of data to insert into this table.

callback BasicCallback <optional>

Callback function.

Source:
See:
Examples
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');
const table = database.table('Singers');

const row = {
  SingerId: 'Id3',
  Name: 'Eddie Wilson'
};

table.insert(row, function(err, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  // Rows inserted successfully.
});

//-
// Multiple rows can be inserted at once.
//-
const row2 = {
  SingerId: 'Id3b',
  Name: 'Joe West'
};

table.insert([
  row,
  row2
], function(err, apiResponse) {});

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

include:samples/crud.js

region_tag:spanner_insert_data
Full example:

read(query, options, callbackopt) → {Promise.<TableReadResponse>}

Receive rows from the database using key lookups and scans.

Performance Considerations:

This method wraps the streaming method, Table#createReadStream for your convenience. All rows will be stored in memory before being released to your callback. If you intend on receiving a lot of results from your query, consider using the streaming method, so you can free each result from memory after consuming it.

Parameters:
Name Type Attributes Description
query ReadRequest

Configuration object, describing what to read from the table.

options TimestampBounds

Transaction options.

callback TableReadCallback <optional>

Callback function.

Source:
Examples
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');
const table = database.table('Singers');

const query = {
  keys: ['1'],
  columns: ['SingerId', 'name']
};

table.read(query, function(err, rows) {
  if (err) {
    // Error handling omitted.
  }

  const firstRow = rows[0];

  // firstRow = [
  //   {
  //     name: 'SingerId',
  //     value: '1'
  //   },
  //   {
  //     name: 'Name',
  //     value: 'Eddie Wilson'
  //   }
  // ]
});

//-
// Provide an array for `query.keys` to read with a composite key.
//-
const query = {
  keys: [
    [
      'Id1',
      'Name1'
    ],
    [
      'Id2',
      'Name2'
    ]
  ],
  // ...
};

//-
// Rows are returned as an array of object arrays. Each object has a `name`
// and `value` property. To get a serialized object, call `toJSON()`.
//
// Alternatively, set `query.json` to `true`, and this step will be
performed
// automatically.
//-
table.read(query, function(err, rows) {
  if (err) {
    // Error handling omitted.
  }

  const firstRow = rows[0];

  // firstRow.toJSON() = {
  //   SingerId: '1',
  //   Name: 'Eddie Wilson'
  // }
});

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

include:samples/crud.js

region_tag:spanner_read_data
Full example:

include:samples/crud.js

region_tag:spanner_read_stale_data
Reading stale data:

include:samples/indexing.js

region_tag:spanner_read_data_with_index
Reading data using an index:

include:samples/indexing.js

region_tag:spanner_read_data_with_storing_index
Reading data using a storing index:

replace(rows, callbackopt) → {Promise.<BasicResponse>}

Replace rows of data within this table.

Parameters:
Name Type Attributes Description
rows object | Array.<object>

A map of names to values of data to insert into this table.

callback BasicCallback <optional>

Callback function.

Source:
See:
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');
const table = database.table('Singers');

const row = {
  SingerId: 'Id3',
  Name: 'Joe West'
};

table.replace(row, function(err, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  // Row replaced successfully.
});

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

update(rows, callbackopt) → {Promise.<BasicResponse>}

Update rows of data within this table.

Parameters:
Name Type Attributes Description
rows object | Array.<object>

A map of names to values of data to insert into this table.

callback BasicCallback <optional>

Callback function.

Source:
See:
Examples
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');
const table = database.table('Singers');

const row = {
  SingerId: 'Id3',
  Name: 'Joe West'
};

table.update(row, function(err, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  // Row updated successfully.
});

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

include:samples/crud.js

region_tag:spanner_update_data
Full example:

upsert(rows, callbackopt) → {Promise.<BasicResponse>}

Insert or update rows of data within this table.

Parameters:
Name Type Attributes Description
rows object | Array.<object>

A map of names to values of data to insert into this table.

callback BasicCallback <optional>

Callback function.

Source:
See:
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');
const table = database.table('Singers');

const row = {
  SingerId: 'Id3',
  Name: 'Joe West'
};

table.upsert(row, function(err, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  // Row inserted or updated successfully.
});

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