This transaction type provides guaranteed consistency across several reads, but does not allow writes. Snapshot read-only transactions can be configured to read at timestamps in the past.
When finished with the Snapshot, call to release the underlying Session . Failure to do so can result in a Session leak.
**This object is created and returned from .**
Inheritance
EventEmitter > SnapshotPackage
@google-cloud/spannerExample
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
();
});
Constructors
(constructor)(session, options, queryOptions)
constructor
(
session
:
Session
,
options
?:
TimestampBounds
,
queryOptions
?:
IQueryOptions
);
Constructs a new instance of the Snapshot
class
session
options
TimestampBounds
Snapshot timestamp bounds.
queryOptions
Properties
_idWaiter
protected
_idWaiter
:
Readable
;
_inlineBeginStarted
protected
_inlineBeginStarted
:
any
;
_options
protected
_options
:
spannerClient
.
spanner
.
v1
.
ITransactionOptions
;
_seqno
protected
_seqno
:
number
;
_useInRunner
protected
_useInRunner
:
boolean
;
ended
ended
:
boolean
;
id
id
?:
Uint8Array
|
string
;
metadata
metadata
?:
spannerClient
.
spanner
.
v1
.
ITransaction
;
queryOptions
queryOptions
?:
IQueryOptions
;
readTimestamp
readTimestamp
?:
PreciseDate
;
readTimestampProto
readTimestampProto
?:
spannerClient
.
protobuf
.
ITimestamp
;
request
request
:
(
config
:
{},
callback
:
Function
)
=
>
void
;
requestOptions
requestOptions
?:
Pick<IRequestOptions
,
'transactionTag'
> ;
requestStream
requestStream
:
(
config
:
{})
=
>
Readable
;
resourceHeader_
resourceHeader_
:
{
[
k
:
string
]
:
string
;
};
session
session
:
Session
;
Methods
_getSpanner()
protected
_getSpanner
()
:
Spanner
;
Gets the Spanner object
_update(resp)
protected
_update
(
resp
:
spannerClient
.
spanner
.
v1
.
ITransaction
)
:
void
;
Update transaction properties from the response.
void
begin(gaxOptions)
begin
(
gaxOptions
?:
CallOptions
)
:
Promise<BeginResponse>
;
Begin a new transaction. Typically, you need not call this unless manually creating transactions via Session objects.
gaxOptions
Promise
< BeginResponse
>
{Promise
transaction
.
begin
(
function
(
err
)
{
if
(
!
err
)
{
// transaction began successfully.
}
});
If the callback is omitted, the function returns a Promise
transaction
.
begin
()
.
then
(
function
(
data
)
{
const
apiResponse
=
data
[
0
];
});
begin(callback)
begin
(
callback
:
BeginTransactionCallback
)
:
void
;
callback
BeginTransactionCallback
void
begin(gaxOptions, callback)
begin
(
gaxOptions
:
CallOptions
,
callback
:
BeginTransactionCallback
)
:
void
;
gaxOptions
CallOptions
callback
BeginTransactionCallback
void
configureTagOptions(singleUse, transactionTag, requestOptions)
configureTagOptions
(
singleUse
?:
boolean
,
transactionTag
?:
string
,
requestOptions
?:
{})
:
IRequestOptions
|
null
;
singleUse
boolean
transactionTag
string
requestOptions
{}
createReadStream(table, request)
createReadStream
(
table
:
string
,
request
?:
ReadRequest
)
:
PartialResultStream
;
Create a readable object stream to receive rows from the database using key lookups and scans.
Wrapper around .
table
string
The table to read from.
request
ReadRequest
PartialResultStream
{ReadableStream} A readable stream that emits rows.
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
();
});
encodeKeySet(request)
static
encodeKeySet
(
request
:
ReadRequest
)
:
spannerClient
.
spanner
.
v1
.
IKeySet
;
Transforms convenience options keys
and ranges
into a KeySet object.
request
ReadRequest
The read request.
encodeParams(request)
static
encodeParams
(
request
:
ExecuteSqlRequest
)
:
{
params
:
p
.
IStruct
;
paramTypes
:
{
[
field
:
string
]
:
spannerClient
.
spanner
.
v1
.
Type
;
};
};
Encodes convenience options param
and types
into the proto formatted.
request
ExecuteSqlRequest
The SQL request.
{
params: common.IStruct
;
paramTypes: {
[field: string]: spannerClient.spanner.v1.Type
;
};
}
{object}
encodeTimestampBounds(options)
static
encodeTimestampBounds
(
options
:
TimestampBounds
)
:
spannerClient
.
spanner
.
v1
.
TransactionOptions
.
IReadOnly
;
Formats timestamp options into proto format.
options
TimestampBounds
The user supplied options.
end()
end
()
:
void
;
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.
void
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(table, request)
read
(
table
:
string
,
request
:
ReadRequest
)
:
Promise<ReadResponse>
;
Performs a read request against the specified Table.
Wrapper around .
table
string
The table to read from.
request
ReadRequest
Promise
< ReadResponse
>
{Promise
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'
// }
// ]
});
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
.
read
(
'Singers'
,
query
,
function
(
err
,
rows
)
{
if
(
err
)
{
// Error handling omitted.
}
const
firstRow
=
rows
[
0
];
// firstRow.toJSON() = {
// SingerId: '1',
// Name: 'Eddie Wilson'
// }
});
Alternatively, set query.json
to true
, and this step will perform automatically.
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'
// }
});
read(table, callback)
read
(
table
:
string
,
callback
:
ReadCallback
)
:
void
;
table
string
callback
ReadCallback
void
read(table, request, callback)
read
(
table
:
string
,
request
:
ReadRequest
,
callback
:
ReadCallback
)
:
void
;
table
string
request
ReadRequest
callback
ReadCallback
void
run(query)
run
(
query
:
string
|
ExecuteSqlRequest
)
:
Promise<RunResponse>
;
Execute a SQL statement on this database inside of a transaction.
**Performance Considerations:**
This method wraps the streaming method, 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 .
query
string | ExecuteSqlRequest
A SQL query or object.
Promise
< RunResponse
>
{Promise
transaction
.
run
(
query
,
function
(
err
,
rows
)
{
if
(
err
)
{
// Error handling omitted.
}
// rows = [
// {
// SingerId: '1',
// Name: 'Eddie Wilson'
// }
// ]
});
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
.
run
(
query
,
function
(
err
,
rows
)
{
if
(
err
)
{
// Error handling omitted.
}
});
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.
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.
}
});
run(query, callback)
run
(
query
:
string
|
ExecuteSqlRequest
,
callback
:
RunCallback
)
:
void
;
query
string | ExecuteSqlRequest
callback
RunCallback
void
runStream(query)
runStream
(
query
:
string
|
ExecuteSqlRequest
)
:
PartialResultStream
;
Create a readable object stream to receive resulting rows from a SQL statement.
Wrapper around .
query
string | ExecuteSqlRequest
A SQL query or object.
PartialResultStream
{ReadableStream}
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
();
});
