Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update documentation for snapshot usage #94

Merged
merged 2 commits into from Jun 9, 2020
Merged

docs: update documentation for snapshot usage #94

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5a34f4e
docs: update documentation for snapshot usage
larkee Jun 4, 2020
627eb32
Merge branch 'master' into update-snapshot-usage
larkee Jun 5, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
35 changes: 21 additions & 14 deletions docs/snapshot-usage.rst
View file
Open in desktop
@@ -1,8 +1,8 @@
Read-only Transactions via Snapshots
####################################

A :class:`~google.cloud.spanner.snapshot.Snapshot` represents a read-only
transaction: when multiple read operations are peformed via a Snapshot,
A :class:`~google.cloud.spanner_v1.snapshot.Snapshot` represents a read-only
transaction: when multiple read operations are performed via a Snapshot,
the results are consistent as of a particular point in time.


Expand All @@ -15,7 +15,8 @@ transactions are visible:

.. code:: python

snapshot = database.snapshot()
with database.snapshot() as snapshot:
...

You can also specify a weaker bound, which can either be to perform all
reads as of a given timestamp:
Expand All @@ -25,15 +26,19 @@ reads as of a given timestamp:
import datetime
from pytz import UTC
TIMESTAMP = datetime.datetime.utcnow().replace(tzinfo=UTC)
snapshot = database.snapshot(read_timestamp=TIMESTAMP)

with database.snapshot(read_timestamp=TIMESTAMP) as snapshot:
...

or as of a given duration in the past:

.. code:: python

import datetime
DURATION = datetime.timedelta(seconds=5)
snapshot = database.snapshot(exact_staleness=DURATION)

with database.snapshot(exact_staleness=DURATION) as snapshot:
...

Single Use and Multiple Use Snapshots
-------------------------------------
Expand All @@ -48,18 +53,19 @@ reused.

.. code:: python

snapshot = database.snapshot(multi_use=True)
with database.snapshot(multi_use=True) as snapshot:
...

:meth:`~.spanner_v1.snapshot.Snapshot.begin` can only be used on a
:meth:`~google.cloud.spanner_v1.snapshot.Snapshot.begin` can only be used on a
snapshot with ``multi_use=True``. In which case it is also necessary
to call if you need to have multiple pending operations.

Read Table Data
---------------

Read data for selected rows from a table in the database. Calls
the ``Read`` API, which returns all rows specified in ``key_set``, or else
fails if the result set is too large,
To read data for selected rows from a table in the database, call
:meth:`~google.cloud.spanner_v1.snapshot.Snapshot.read` which will return
all rows specified in ``key_set``, or fail if the result set is too large,

.. code:: python

Expand All @@ -73,16 +79,17 @@ fails if the result set is too large,

.. note::

Perform all iteration within the context of the ``with database.snapshot()``
Perform all iterations within the context of the ``with database.snapshot()``
block.


Execute a SQL Select Statement
------------------------------

Read data from a query against tables in the database. Calls
the ``ExecuteSql`` API, which returns all rows matching the query, or else
fails if the result set is too large,
To read data from tables in the database using a query, call
:meth:`~google.cloud.spanner_v1.snapshot.Snapshot.execute_sql`
which will return all rows matching the query, or fail if the
result set is too large,

.. code:: python

Expand Down