Snapshot - Documentation

Constructor

new Snapshot(session, optionsopt, queryOptionsopt)

Parameters:

Name	Type	Attributes	Description
`session`	Session		The parent Session object.
`options`	TimestampBounds	<optional>	Snapshot timestamp bounds.
`queryOptions`	QueryOptions	<optional>	Default query options to use when none are specified for a query.

See:

Timestamp Bounds API Documentation

Example

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

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

const timestampBounds = {
  strong: true
};

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

  // It should be called when the snapshot finishes.
  transaction.end();
});
```

Members

ended

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

id

The transaction ID.

metadata

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

readTimestamp

Snapshot only The timestamp at which all reads are performed.

readTimestampProto

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

Methods

(protected) _setMutationKey(mutations)

Selects a single representative mutation from a list to be used as the transaction's mutationKey.

This key is required by Spanner and is sent in the BeginTransactionRequest for read-write transactions that only contain mutations. The selection follows a two-tiered heuristic to choose the most significant mutation.

The selection heuristic is as follows:

Priority of Operation Type: High-priority mutations (delete, update, replace, insertOrUpdate) are always chosen over low-priority (insert) mutations.
Selection Strategy:

If any high-priority mutations exist, one is chosen randomly from that group, ignoring the number of rows.
If only insert mutations exist, the one(s) with the largest number of rows are identified, and one is chosen randomly from that subset.

Parameters:

Name	Type	Description
`mutations`		The list of mutations from which to select the key.

(protected) _setPreviousTransactionId(transaction)

Modifies transaction selector to include the multiplexed session previous transaction id. This is essential for operations that use an inline begin.

Parameters:

Name	Type	Description
`transaction`		The transaction selector object that will be mutated to include the multiplexed session previous transaction id.

createReadStream(table, query) → {ReadableStream}

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

Wrapper around v1.SpannerClient#streamingRead.

Parameters:

Name	Type	Description
`table`	string	The table to read from.
`query`	ReadRequest	Configuration object. See official `ReadRequest`. API documentation.

Returns:

Type	Description
ReadableStream	A readable stream that emits rows.

See:

Fires:

PartialResultStream#event:response
PartialResultStream#event:stats

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.
  });

```

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

Alternatively, set `query.json` to `true`, and this step
will perform automatically.
```
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.
  });
```

If you anticipate many results, you can end a stream
early to prevent unnecessary processing and API requests.
```
transaction.createReadStream('Singers', {
    keys: ['1'],
    columns: ['SingerId', 'name']
  })
  .on('data', function(row) {
    this.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.

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

runStream(query) → {ReadableStream}

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

Wrapper around v1.SpannerClient#executeStreamingSql.

Parameters:

Name	Type	Description
`query`	string \| ExecuteSqlRequest	A SQL query or ExecuteSqlRequest object.

Returns:

Type	Description
ReadableStream

See:

Fires:

PartialResultStream#event:response
PartialResultStream#event:stats

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.
  });

```

The SQL query string can contain parameter placeholders.
A parameter placeholder consists of '@' followed by the parameter name.
```
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() {});
```

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