Constructor

PartitionedDml

new PartitionedDml()

Extends
Snapshot
See also
Database#runPartitionedUpdate

Properties

ended

unknown

Whether or not the transaction has ended. If true, make no further requests, and discard the transaction.

Inherited from
Snapshot#ended

id

unknown

The transaction ID.

Inherited from
Snapshot#id

metadata

unknown

The raw transaction response object. It is populated after Snapshot#begin is called.

Inherited from
Snapshot#metadata

readTimestamp

unknown

Snapshot only The timestamp at which all reads are performed.

Inherited from
Snapshot#readTimestamp

readTimestampProto

unknown

Snapshot only The protobuf version of Snapshot#readTimestamp. This is useful if you require microsecond precision.

Inherited from
Snapshot#readTimestampProto

Methods

begin

begin(callback) returns Promise containing TransactionBeginResponse

Begin a new transaction. Typically, you need not call this unless manually creating transactions via Session objects.

Parameter

callback

Optional

Callback function.

Inherited from
Snapshot#begin
See also

BeginTransaction API Documentation

Returns

Examples

transaction.begin(function(err) {
  if (!err) {
    // transaction began successfully.
  }
});
<caption>If the callback is omitted, the function returns a Promise
</caption>
transaction.begin()
  .then(function(data) {
    const apiResponse = data[0];
  });

createReadStream

createReadStream(table, query) returns ReadableStream

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

Wrapper around v1.SpannerClient#streamingRead.

Parameter

table

The table to read from.

query

Configuration object. See official ReadRequest. API documentation.

Inherited from
Snapshot#createReadStream
See also
v1.SpannerClient#streamingRead

StreamingRead API Documentation

ReadRequest API Documentation

Fires
PartialResultStream#event:response
PartialResultStream#event:stats
Returns

A readable stream that emits rows.

Examples

transaction.createReadStream('Singers', {
    keys: ['1'],
    columns: ['SingerId', 'name']
  })
  .on('error', function(err) {})
  .on('data', function(row) {
    // row = [
    //   {
    //     name: 'SingerId',
    //     value: '1'
    //   },
    //   {
    //     name: 'Name',
    //     value: 'Eddie Wilson'
    //   }
    // ]
  })
  .on('end', function() {
    // All results retrieved.
  });
<caption>Provide an array for `query.keys` to read with a
composite key.</caption>
const query = {
  keys: [
    [
      'Id1',
      'Name1'
    ],
    [
      'Id2',
      'Name2'
    ]
  ],
  // ...
};
<caption>Rows are returned as an array of object arrays. Each
object has a `name` and `value` property. To get a serialized object, call
`toJSON()`.</caption>
transaction.createReadStream('Singers', {
    keys: ['1'],
    columns: ['SingerId', 'name']
  })
  .on('error', function(err) {})
  .on('data', function(row) {
    // row.toJSON() = {
    //   SingerId: '1',
    //   Name: 'Eddie Wilson'
    // }
  })
  .on('end', function() {
    // All results retrieved.
  });
<caption>Alternatively, set `query.json` to `true`, and this step
will perform automatically.</caption>
transaction.createReadStream('Singers', {
    keys: ['1'],
    columns: ['SingerId', 'name'],
    json: true,
  })
  .on('error', function(err) {})
  .on('data', function(row) {
    // row = {
    //   SingerId: '1',
    //   Name: 'Eddie Wilson'
    // }
  })
  .on('end', function() {
    // All results retrieved.
  });
<caption>If you anticipate many results, you can end a stream
early to prevent unnecessary processing and API requests.</caption>
transaction.createReadStream('Singers', {
    keys: ['1'],
    columns: ['SingerId', 'name']
  })
  .on('data', function(row) {
    this.end();
  });

end

end()

Let the client know you're done with a particular transaction. This should mainly be called for Snapshot objects, however in certain cases you may want to call them for Transaction objects as well.

Inherited from
Snapshot#end

Examples

Calling `end` on a read only snapshot

database.getSnapshot((err, transaction) => {
  if (err) {
    // Error handling omitted.
  }

  transaction.run('SELECT * FROM Singers', (err, rows) => {
    if (err) {
      // Error handling omitted.
    }

    // End the snapshot.
    transaction.end();
  });
});

Calling `end` on a read/write transaction

database.runTransaction((err, transaction) => {
  if (err) {
    // Error handling omitted.
  }

  const query = 'UPDATE Account SET Balance = 1000 WHERE Key = 1';

  transaction.runUpdate(query, err => {
    if (err) {
      // In the event of an error, there would be nothing to rollback,
so
      // instead of continuing, discard the
transaction. transaction.end(); return;
    }

    transaction.commit(err => {});
  });
});

read

read(table, query, callback) returns Promise containing TransactionRequestReadResponse

Performs a read request against the specified Table.

Wrapper around v1.SpannerClient#read.

Parameter

table

The table to read from.

query

Configuration object. See official ReadRequest. API documentation.

callback

Optional

Callback function.

Inherited from
Snapshot#read
See also
v1.SpannerClient#read
Returns

Examples

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

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

  const firstRow = rows[0];

  // firstRow = [
  //   {
  //     name: 'SingerId',
  //     value: '1'
  //   },
  //   {
  //     name: 'Name',
  //     value: 'Eddie Wilson'
  //   }
  // ]
});
<caption>Provide an array for `query.keys` to read with a
composite key.</caption>
const query = {
  keys: [
    [
      'Id1',
      'Name1'
    ],
    [
      'Id2',
      'Name2'
    ]
  ],
  // ...
};
<caption>Rows are returned as an array of object arrays. Each
object has a `name` and `value` property. To get a serialized object, call
`toJSON()`.</caption>
transaction.read('Singers', query, function(err, rows) {
  if (err) {
    // Error handling omitted.
  }

  const firstRow = rows[0];

  // firstRow.toJSON() = {
  //   SingerId: '1',
  //   Name: 'Eddie Wilson'
  // }
});
<caption>Alternatively, set `query.json` to `true`, and this step
will perform automatically.</caption>
query.json = true;

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

  const firstRow = rows[0];

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

run

run(query, callback) returns Promise containing RunResponse

Execute a SQL statement on this database inside of a transaction.

Performance Considerations:

This method wraps the streaming method, Snapshot#run for your convenience. All rows are stored in memory before releasing to your callback. If you intend to receive a lot of results from your query, consider using the streaming method, so you can free each result from memory after consuming it.

Wrapper around v1.SpannerClient#executeStreamingSql.

Parameter

query

A SQL query or ExecuteSqlRequest object.

callback

Optional

Callback function.

Inherited from
Snapshot#run
See also
v1.SpannerClient#executeStreamingSql

ExecuteStreamingSql API Documentation

ExecuteSqlRequest API Documentation

Returns

Examples

transaction.run(query, function(err, rows) {
  if (err) {
    // Error handling omitted.
  }

  // rows = [
  //   {
  //     SingerId: '1',
  //     Name: 'Eddie Wilson'
  //   }
  // ]
});
<caption>The SQL query string can contain parameter placeholders.
A parameter placeholder consists of '@' followed by the parameter name.
</caption>
const query = {
  sql: 'SELECT * FROM Singers WHERE name = @name',
  params: {
    name: 'Eddie Wilson'
  }
};

transaction.run(query, function(err, rows) {
  if (err) {
    // Error handling omitted.
  }
});
<caption>If you need to enforce a specific param type, a types map
can be provided. This is typically useful if your param value can be null.
</caption>
const query = {
  sql: 'SELECT * FROM Singers WHERE name = @name AND id = @id',
  params: {
    id: spanner.int(8),
    name: null
  },
  types: {
    id: 'int64',
    name: 'string'
  }
};

transaction.run(query, function(err, rows) {
  if (err) {
    // Error handling omitted.
  }
});

runStream

runStream(query) returns ReadableStream

Create a readable object stream to receive resulting rows from a SQL statement.

Wrapper around v1.SpannerClient#executeStreamingSql.

Parameter

query

A SQL query or ExecuteSqlRequest object.

Inherited from
Snapshot#runStream
See also
v1.SpannerClient#executeStreamingSql

ExecuteStreamingSql API Documentation

ExecuteSqlRequest API Documentation

Fires
PartialResultStream#event:response
PartialResultStream#event:stats
Returns

Examples

const query = 'SELECT * FROM Singers';

transaction.runStream(query)
  .on('error', function(err) {})
  .on('data', function(row) {
    // row = {
    //   SingerId: '1',
    //   Name: 'Eddie Wilson'
    // }
  })
  .on('end', function() {
    // All results retrieved.
  });
<caption>The SQL query string can contain parameter placeholders.
A parameter placeholder consists of '@' followed by the parameter name.
</caption>
const query = {
  sql: 'SELECT * FROM Singers WHERE name = @name',
  params: {
    name: 'Eddie Wilson'
  }
};

transaction.runStream(query)
  .on('error', function(err) {})
  .on('data', function(row) {})
  .on('end', function() {});
<caption>If you anticipate many results, you can end a stream
early to prevent unnecessary processing and API requests.</caption>
transaction.runStream(query)
  .on('data', function(row) {
    this.end();
  });

runUpdate

runUpdate(query, callback) returns Promise containing RunUpdateResponse

Execute a DML statement and get the affected row count. Unlike Transaction#runUpdate after using this method you should immediately discard this transaction, internally it will invoke PartitionedDml#end.

Parameter

query

(string or object)

A DML statement or ExecuteSqlRequest object.

Values in query have the following properties:

Parameter

params

Optional

object

A map of parameter name to values.

types

Optional

object

A map of parameter types.

callback

Optional

RunUpdateCallback

Callback function.

See also
Database#runPartitionedUpdate
Returns

Promise containing RunUpdateResponse 

Example

transaction.runUpdate(query, (err, rowRount) => {
  if (err) {
    // Error handling omitted.
  }
});