Table
Create a Table object to interact with a table in a Cloud Spanner database.
Constructor
Table
new Table(database, name)
Parameter |
|
---|---|
database |
Database instance. |
name |
string Name of the table. |
- Extends
- TransactionRequest
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');
Properties
api
object
Properties
Parameter |
|
---|---|
Database |
Reference to an instance of the low-level v1.DatabaseAdminClient class used by this Table instance. |
Instance |
Reference to an instance of the low-level v1.InstanceAdminClient class used by this Table instance. |
Spanner |
Reference to an instance of the low-level v1.SpannerClient class used by this Table instance. |
database
The Database instance of this Table instance.
name
string
The name of this table.
Methods
create
create(schema, callback) returns Promise containing CreateTableResponse
Create a table.
Parameter |
|
---|---|
schema |
string See Database#createTable. |
callback |
Optional Callback function. |
- Returns
-
Promise containing CreateTableResponse
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
createReadStream(query, options) returns ReadableStream
Create a readable object stream to receive rows from the database using key lookups and scans.
Parameter |
|
---|---|
query |
Configuration object. See
|
options |
Optional |
- See also
- Returns
-
ReadableStream
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
delete(callback) returns Promise containing LongRunningOperationResponse
Delete the table. Not to be confused with Table#deleteRows.
Wrapper around Database#updateSchema.
Parameter |
|
---|---|
callback |
Optional Callback function. |
- See also
- Database#updateSchema
- Throws
-
TypeError
If any arguments are passed in.
- Returns
-
Promise containing LongRunningOperationResponse
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
deleteRows(keys, callback) returns Promise containing BasicResponse
Delete rows from this table.
Parameter |
|
---|---|
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 |
Optional Callback function. |
- See also
- Returns
-
Promise containing BasicResponse
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
drop(callback) returns Promise containing LongRunningOperationResponse
Drop the table.
Parameter |
|
---|---|
callback |
Optional Callback function. |
- See also
- Table#delete
- Database#updateSchema
- Returns
-
Promise containing LongRunningOperationResponse
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
insert(keyVals, callback) returns Promise containing BasicResponse
Insert rows of data into this table.
Parameter |
|
---|---|
keyVals |
(object or Array of object) A map of names to values of data to insert into this table. |
callback |
Optional Callback function. |
- See also
- Returns
-
Promise containing BasicResponse
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: '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];
});
Full example:
queue_
queue_(mutation)
This probably should be implemented as an abstract method, but it doesn't appear to be implemented in the Table class which extends it.
Parameter |
|
---|---|
mutation |
- Inherited from
- TransactionRequest#queue_
read
read(query, options, callback) returns Promise containing 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.
Parameter |
|
---|---|
query |
Configuration object, describing what to read from the table. |
options |
|
callback |
Optional Callback function. |
- Returns
-
Promise containing TableReadResponse
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 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
// automaticaly.
//-
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 apiResponse = data[0];
});
Full example:
Reading stale data:
Reading data using an index:
Reading data using a storing index:
replace
replace(keyVals, callback) returns Promise containing BasicResponse
Replace rows of data within this table.
Parameter |
|
---|---|
keyVals |
(object or Array of object) A map of names to values of data to insert into this table. |
callback |
Optional Callback function. |
- See also
- Returns
-
Promise containing BasicResponse
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
update(keyVals, callback) returns Promise containing BasicResponse
Update rows of data within this table.
Parameter |
|
---|---|
keyVals |
(object or Array of object) A map of names to values of data to insert into this table. |
callback |
Optional Callback function. |
- See also
- Returns
-
Promise containing BasicResponse
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.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];
});
Full example:
upsert
upsert(keyVals, callback) returns Promise containing BasicResponse
Insert or update rows of data within this table.
Parameter |
|
---|---|
keyVals |
(object or Array of object) A map of names to values of data to insert into this table. |
callback |
Optional Callback function. |
- See also
- Returns
-
Promise containing BasicResponse
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.update(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.update(row)
.then(function(data) {
const apiResponse = data[0];
});