docs: update docs (#916)
* fix: re-run script
* test: fix noxfile
diff --git a/docs/dyn/spanner_v1.projects.instances.databases.sessions.html b/docs/dyn/spanner_v1.projects.instances.databases.sessions.html
index 1632d41..064238a 100644
--- a/docs/dyn/spanner_v1.projects.instances.databases.sessions.html
+++ b/docs/dyn/spanner_v1.projects.instances.databases.sessions.html
@@ -102,7 +102,7 @@
<code><a href="#get">get(name, x__xgafv=None)</a></code></p>
<p class="firstline">Gets a session. Returns `NOT_FOUND` if the session does not exist.</p>
<p class="toc_element">
- <code><a href="#list">list(database, filter=None, pageToken=None, pageSize=None, x__xgafv=None)</a></code></p>
+ <code><a href="#list">list(database, filter=None, pageSize=None, pageToken=None, x__xgafv=None)</a></code></p>
<p class="firstline">Lists all sessions in a given database.</p>
<p class="toc_element">
<code><a href="#list_next">list_next(previous_request, previous_response)</a></code></p>
@@ -137,11 +137,9 @@
{ # The request for BatchCreateSessions.
"sessionTemplate": { # A session in the Cloud Spanner API. # Parameters to be applied to each created session.
- "approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is
- # typically earlier than the actual last use time.
+ "createTime": "A String", # Output only. The timestamp when the session is created.
"name": "A String", # The name of the session. This is always system-assigned; values provided
# when creating a session are ignored.
- "createTime": "A String", # Output only. The timestamp when the session is created.
"labels": { # The labels for the session.
#
# * Label keys must be between 1 and 63 characters long and must conform to
@@ -153,6 +151,8 @@
# See https://goo.gl/xmQnxf for more information on and examples of labels.
"a_key": "A String",
},
+ "approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is
+ # typically earlier than the actual last use time.
},
"sessionCount": 42, # Required. The number of sessions to be created in this batch call.
# The API may return fewer than the requested number of sessions. If a
@@ -172,11 +172,9 @@
{ # The response for BatchCreateSessions.
"session": [ # The freshly created sessions.
{ # A session in the Cloud Spanner API.
- "approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is
- # typically earlier than the actual last use time.
+ "createTime": "A String", # Output only. The timestamp when the session is created.
"name": "A String", # The name of the session. This is always system-assigned; values provided
# when creating a session are ignored.
- "createTime": "A String", # Output only. The timestamp when the session is created.
"labels": { # The labels for the session.
#
# * Label keys must be between 1 and 63 characters long and must conform to
@@ -188,6 +186,8 @@
# See https://goo.gl/xmQnxf for more information on and examples of labels.
"a_key": "A String",
},
+ "approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is
+ # typically earlier than the actual last use time.
},
],
}</pre>
@@ -489,33 +489,18 @@
# `spanner.databases.beginPartitionedDmlTransaction` permission
# on the `session` resource.
},
+ "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
+ #
+ # Authorization to begin a read-write transaction requires
+ # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
+ # on the `session` resource.
+ # transaction type has no options.
+ },
"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
#
# Authorization to begin a read-only transaction requires
# `spanner.databases.beginReadOnlyTransaction` permission
# on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
# seconds. Guarantees that all writes that have committed more
# than the specified number of seconds ago are visible. Because
@@ -529,6 +514,18 @@
#
# Note that this option can only be used in single-use
# transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
# the Transaction message that describes the transaction.
"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
@@ -542,15 +539,18 @@
#
# Useful for reading at nearby replicas without the distributed
# timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
- },
- "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
- #
- # Authorization to begin a read-write transaction requires
- # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
- # on the `session` resource.
- # transaction type has no options.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
},
},
}
@@ -564,6 +564,12 @@
An object of the form:
{ # A transaction.
+ "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
+ # for the transaction. Not returned by default: see
+ # TransactionOptions.ReadOnly.return_read_timestamp.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
"id": "A String", # `id` may be used to identify the transaction in subsequent
# Read,
# ExecuteSql,
@@ -572,12 +578,6 @@
#
# Single-use read-only transactions do not have IDs, because
# single-use transactions do not support multiple requests.
- "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
- # for the transaction. Not returned by default: see
- # TransactionOptions.ReadOnly.return_read_timestamp.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
}</pre>
</div>
@@ -598,257 +598,7 @@
The object takes the form of:
{ # The request for Commit.
- "mutations": [ # The mutations to be executed when this transaction commits. All
- # mutations are applied atomically, in the order they appear in
- # this list.
- { # A modification to one or more Cloud Spanner rows. Mutations can be
- # applied to a Cloud Spanner database by sending them in a
- # Commit call.
- "replace": { # Arguments to insert, update, insert_or_update, and # Like insert, except that if the row already exists, it is
- # deleted, and the column values provided are inserted
- # instead. Unlike insert_or_update, this means any values not
- # explicitly written become `NULL`.
- #
- # In an interleaved table, if you create the child table with the
- # `ON DELETE CASCADE` annotation, then replacing a parent row
- # also deletes the child rows. Otherwise, you must delete the
- # child rows before you replace the parent row.
- # replace operations.
- "table": "A String", # Required. The table whose rows will be written.
- "values": [ # The values to be written. `values` can contain more than one
- # list of values. If it does, then multiple rows are written, one
- # for each entry in `values`. Each list in `values` must have
- # exactly as many entries as there are entries in columns
- # above. Sending multiple lists is equivalent to sending multiple
- # `Mutation`s, each containing one `values` entry and repeating
- # table and columns. Individual values in each list are
- # encoded as described here.
- [
- "",
- ],
- ],
- "columns": [ # The names of the columns in table to be written.
- #
- # The list of columns must contain enough columns to allow
- # Cloud Spanner to derive values for all primary key columns in the
- # row(s) to be modified.
- "A String",
- ],
- },
- "delete": { # Arguments to delete operations. # Delete rows from a table. Succeeds whether or not the named
- # rows were present.
- "keySet": { # `KeySet` defines a collection of Cloud Spanner keys and/or key ranges. All # Required. The primary keys of the rows within table to delete. The
- # primary keys must be specified in the order in which they appear in the
- # `PRIMARY KEY()` clause of the table's equivalent DDL statement (the DDL
- # statement used to create the table).
- # Delete is idempotent. The transaction will succeed even if some or all
- # rows do not exist.
- # the keys are expected to be in the same table or index. The keys need
- # not be sorted in any particular way.
- #
- # If the same key is specified multiple times in the set (for example
- # if two ranges, two keys, or a key and a range overlap), Cloud Spanner
- # behaves as if the key were only specified once.
- "ranges": [ # A list of key ranges. See KeyRange for more information about
- # key range specifications.
- { # KeyRange represents a range of rows in a table or index.
- #
- # A range has a start key and an end key. These keys can be open or
- # closed, indicating if the range includes rows with that key.
- #
- # Keys are represented by lists, where the ith value in the list
- # corresponds to the ith component of the table or index primary key.
- # Individual values are encoded as described
- # here.
- #
- # For example, consider the following table definition:
- #
- # CREATE TABLE UserEvents (
- # UserName STRING(MAX),
- # EventDate STRING(10)
- # ) PRIMARY KEY(UserName, EventDate);
- #
- # The following keys name rows in this table:
- #
- # "Bob", "2014-09-23"
- #
- # Since the `UserEvents` table's `PRIMARY KEY` clause names two
- # columns, each `UserEvents` key has two elements; the first is the
- # `UserName`, and the second is the `EventDate`.
- #
- # Key ranges with multiple components are interpreted
- # lexicographically by component using the table or index key's declared
- # sort order. For example, the following range returns all events for
- # user `"Bob"` that occurred in the year 2015:
- #
- # "start_closed": ["Bob", "2015-01-01"]
- # "end_closed": ["Bob", "2015-12-31"]
- #
- # Start and end keys can omit trailing key components. This affects the
- # inclusion and exclusion of rows that exactly match the provided key
- # components: if the key is closed, then rows that exactly match the
- # provided components are included; if the key is open, then rows
- # that exactly match are not included.
- #
- # For example, the following range includes all events for `"Bob"` that
- # occurred during and after the year 2000:
- #
- # "start_closed": ["Bob", "2000-01-01"]
- # "end_closed": ["Bob"]
- #
- # The next example retrieves all events for `"Bob"`:
- #
- # "start_closed": ["Bob"]
- # "end_closed": ["Bob"]
- #
- # To retrieve events before the year 2000:
- #
- # "start_closed": ["Bob"]
- # "end_open": ["Bob", "2000-01-01"]
- #
- # The following range includes all rows in the table:
- #
- # "start_closed": []
- # "end_closed": []
- #
- # This range returns all users whose `UserName` begins with any
- # character from A to C:
- #
- # "start_closed": ["A"]
- # "end_open": ["D"]
- #
- # This range returns all users whose `UserName` begins with B:
- #
- # "start_closed": ["B"]
- # "end_open": ["C"]
- #
- # Key ranges honor column sort order. For example, suppose a table is
- # defined as follows:
- #
- # CREATE TABLE DescendingSortedTable {
- # Key INT64,
- # ...
- # ) PRIMARY KEY(Key DESC);
- #
- # The following range retrieves all rows with key values between 1
- # and 100 inclusive:
- #
- # "start_closed": ["100"]
- # "end_closed": ["1"]
- #
- # Note that 100 is passed as the start, and 1 is passed as the end,
- # because `Key` is a descending column in the schema.
- "endOpen": [ # If the end is open, then the range excludes rows whose first
- # `len(end_open)` key columns exactly match `end_open`.
- "",
- ],
- "endClosed": [ # If the end is closed, then the range includes all rows whose
- # first `len(end_closed)` key columns exactly match `end_closed`.
- "",
- ],
- "startOpen": [ # If the start is open, then the range excludes rows whose first
- # `len(start_open)` key columns exactly match `start_open`.
- "",
- ],
- "startClosed": [ # If the start is closed, then the range includes all rows whose
- # first `len(start_closed)` key columns exactly match `start_closed`.
- "",
- ],
- },
- ],
- "all": True or False, # For convenience `all` can be set to `true` to indicate that this
- # `KeySet` matches all keys in the table or index. Note that any keys
- # specified in `keys` or `ranges` are only yielded once.
- "keys": [ # A list of specific keys. Entries in `keys` should have exactly as
- # many elements as there are columns in the primary or index key
- # with which this `KeySet` is used. Individual key values are
- # encoded as described here.
- [
- "",
- ],
- ],
- },
- "table": "A String", # Required. The table whose rows will be deleted.
- },
- "insertOrUpdate": { # Arguments to insert, update, insert_or_update, and # Like insert, except that if the row already exists, then
- # its column values are overwritten with the ones provided. Any
- # column values not explicitly written are preserved.
- #
- # When using insert_or_update, just as when using insert, all `NOT
- # NULL` columns in the table must be given a value. This holds true
- # even when the row already exists and will therefore actually be updated.
- # replace operations.
- "table": "A String", # Required. The table whose rows will be written.
- "values": [ # The values to be written. `values` can contain more than one
- # list of values. If it does, then multiple rows are written, one
- # for each entry in `values`. Each list in `values` must have
- # exactly as many entries as there are entries in columns
- # above. Sending multiple lists is equivalent to sending multiple
- # `Mutation`s, each containing one `values` entry and repeating
- # table and columns. Individual values in each list are
- # encoded as described here.
- [
- "",
- ],
- ],
- "columns": [ # The names of the columns in table to be written.
- #
- # The list of columns must contain enough columns to allow
- # Cloud Spanner to derive values for all primary key columns in the
- # row(s) to be modified.
- "A String",
- ],
- },
- "insert": { # Arguments to insert, update, insert_or_update, and # Insert new rows in a table. If any of the rows already exist,
- # the write or transaction fails with error `ALREADY_EXISTS`.
- # replace operations.
- "table": "A String", # Required. The table whose rows will be written.
- "values": [ # The values to be written. `values` can contain more than one
- # list of values. If it does, then multiple rows are written, one
- # for each entry in `values`. Each list in `values` must have
- # exactly as many entries as there are entries in columns
- # above. Sending multiple lists is equivalent to sending multiple
- # `Mutation`s, each containing one `values` entry and repeating
- # table and columns. Individual values in each list are
- # encoded as described here.
- [
- "",
- ],
- ],
- "columns": [ # The names of the columns in table to be written.
- #
- # The list of columns must contain enough columns to allow
- # Cloud Spanner to derive values for all primary key columns in the
- # row(s) to be modified.
- "A String",
- ],
- },
- "update": { # Arguments to insert, update, insert_or_update, and # Update existing rows in a table. If any of the rows does not
- # already exist, the transaction fails with error `NOT_FOUND`.
- # replace operations.
- "table": "A String", # Required. The table whose rows will be written.
- "values": [ # The values to be written. `values` can contain more than one
- # list of values. If it does, then multiple rows are written, one
- # for each entry in `values`. Each list in `values` must have
- # exactly as many entries as there are entries in columns
- # above. Sending multiple lists is equivalent to sending multiple
- # `Mutation`s, each containing one `values` entry and repeating
- # table and columns. Individual values in each list are
- # encoded as described here.
- [
- "",
- ],
- ],
- "columns": [ # The names of the columns in table to be written.
- #
- # The list of columns must contain enough columns to allow
- # Cloud Spanner to derive values for all primary key columns in the
- # row(s) to be modified.
- "A String",
- ],
- },
- },
- ],
+ "transactionId": "A String", # Commit a previously-started transaction.
"singleUseTransaction": { # # Transactions # Execute mutations in a temporary transaction. Note that unlike
# commit of a previously-started transaction, commit with a
# temporary transaction is non-idempotent. That is, if the
@@ -1140,33 +890,18 @@
# `spanner.databases.beginPartitionedDmlTransaction` permission
# on the `session` resource.
},
+ "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
+ #
+ # Authorization to begin a read-write transaction requires
+ # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
+ # on the `session` resource.
+ # transaction type has no options.
+ },
"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
#
# Authorization to begin a read-only transaction requires
# `spanner.databases.beginReadOnlyTransaction` permission
# on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
# seconds. Guarantees that all writes that have committed more
# than the specified number of seconds ago are visible. Because
@@ -1180,6 +915,18 @@
#
# Note that this option can only be used in single-use
# transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
# the Transaction message that describes the transaction.
"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
@@ -1193,18 +940,271 @@
#
# Useful for reading at nearby replicas without the distributed
# timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
- },
- "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
- #
- # Authorization to begin a read-write transaction requires
- # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
- # on the `session` resource.
- # transaction type has no options.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
},
},
- "transactionId": "A String", # Commit a previously-started transaction.
+ "mutations": [ # The mutations to be executed when this transaction commits. All
+ # mutations are applied atomically, in the order they appear in
+ # this list.
+ { # A modification to one or more Cloud Spanner rows. Mutations can be
+ # applied to a Cloud Spanner database by sending them in a
+ # Commit call.
+ "insert": { # Arguments to insert, update, insert_or_update, and # Insert new rows in a table. If any of the rows already exist,
+ # the write or transaction fails with error `ALREADY_EXISTS`.
+ # replace operations.
+ "table": "A String", # Required. The table whose rows will be written.
+ "values": [ # The values to be written. `values` can contain more than one
+ # list of values. If it does, then multiple rows are written, one
+ # for each entry in `values`. Each list in `values` must have
+ # exactly as many entries as there are entries in columns
+ # above. Sending multiple lists is equivalent to sending multiple
+ # `Mutation`s, each containing one `values` entry and repeating
+ # table and columns. Individual values in each list are
+ # encoded as described here.
+ [
+ "",
+ ],
+ ],
+ "columns": [ # The names of the columns in table to be written.
+ #
+ # The list of columns must contain enough columns to allow
+ # Cloud Spanner to derive values for all primary key columns in the
+ # row(s) to be modified.
+ "A String",
+ ],
+ },
+ "delete": { # Arguments to delete operations. # Delete rows from a table. Succeeds whether or not the named
+ # rows were present.
+ "table": "A String", # Required. The table whose rows will be deleted.
+ "keySet": { # `KeySet` defines a collection of Cloud Spanner keys and/or key ranges. All # Required. The primary keys of the rows within table to delete. The
+ # primary keys must be specified in the order in which they appear in the
+ # `PRIMARY KEY()` clause of the table's equivalent DDL statement (the DDL
+ # statement used to create the table).
+ # Delete is idempotent. The transaction will succeed even if some or all
+ # rows do not exist.
+ # the keys are expected to be in the same table or index. The keys need
+ # not be sorted in any particular way.
+ #
+ # If the same key is specified multiple times in the set (for example
+ # if two ranges, two keys, or a key and a range overlap), Cloud Spanner
+ # behaves as if the key were only specified once.
+ "ranges": [ # A list of key ranges. See KeyRange for more information about
+ # key range specifications.
+ { # KeyRange represents a range of rows in a table or index.
+ #
+ # A range has a start key and an end key. These keys can be open or
+ # closed, indicating if the range includes rows with that key.
+ #
+ # Keys are represented by lists, where the ith value in the list
+ # corresponds to the ith component of the table or index primary key.
+ # Individual values are encoded as described
+ # here.
+ #
+ # For example, consider the following table definition:
+ #
+ # CREATE TABLE UserEvents (
+ # UserName STRING(MAX),
+ # EventDate STRING(10)
+ # ) PRIMARY KEY(UserName, EventDate);
+ #
+ # The following keys name rows in this table:
+ #
+ # "Bob", "2014-09-23"
+ #
+ # Since the `UserEvents` table's `PRIMARY KEY` clause names two
+ # columns, each `UserEvents` key has two elements; the first is the
+ # `UserName`, and the second is the `EventDate`.
+ #
+ # Key ranges with multiple components are interpreted
+ # lexicographically by component using the table or index key's declared
+ # sort order. For example, the following range returns all events for
+ # user `"Bob"` that occurred in the year 2015:
+ #
+ # "start_closed": ["Bob", "2015-01-01"]
+ # "end_closed": ["Bob", "2015-12-31"]
+ #
+ # Start and end keys can omit trailing key components. This affects the
+ # inclusion and exclusion of rows that exactly match the provided key
+ # components: if the key is closed, then rows that exactly match the
+ # provided components are included; if the key is open, then rows
+ # that exactly match are not included.
+ #
+ # For example, the following range includes all events for `"Bob"` that
+ # occurred during and after the year 2000:
+ #
+ # "start_closed": ["Bob", "2000-01-01"]
+ # "end_closed": ["Bob"]
+ #
+ # The next example retrieves all events for `"Bob"`:
+ #
+ # "start_closed": ["Bob"]
+ # "end_closed": ["Bob"]
+ #
+ # To retrieve events before the year 2000:
+ #
+ # "start_closed": ["Bob"]
+ # "end_open": ["Bob", "2000-01-01"]
+ #
+ # The following range includes all rows in the table:
+ #
+ # "start_closed": []
+ # "end_closed": []
+ #
+ # This range returns all users whose `UserName` begins with any
+ # character from A to C:
+ #
+ # "start_closed": ["A"]
+ # "end_open": ["D"]
+ #
+ # This range returns all users whose `UserName` begins with B:
+ #
+ # "start_closed": ["B"]
+ # "end_open": ["C"]
+ #
+ # Key ranges honor column sort order. For example, suppose a table is
+ # defined as follows:
+ #
+ # CREATE TABLE DescendingSortedTable {
+ # Key INT64,
+ # ...
+ # ) PRIMARY KEY(Key DESC);
+ #
+ # The following range retrieves all rows with key values between 1
+ # and 100 inclusive:
+ #
+ # "start_closed": ["100"]
+ # "end_closed": ["1"]
+ #
+ # Note that 100 is passed as the start, and 1 is passed as the end,
+ # because `Key` is a descending column in the schema.
+ "startOpen": [ # If the start is open, then the range excludes rows whose first
+ # `len(start_open)` key columns exactly match `start_open`.
+ "",
+ ],
+ "endClosed": [ # If the end is closed, then the range includes all rows whose
+ # first `len(end_closed)` key columns exactly match `end_closed`.
+ "",
+ ],
+ "endOpen": [ # If the end is open, then the range excludes rows whose first
+ # `len(end_open)` key columns exactly match `end_open`.
+ "",
+ ],
+ "startClosed": [ # If the start is closed, then the range includes all rows whose
+ # first `len(start_closed)` key columns exactly match `start_closed`.
+ "",
+ ],
+ },
+ ],
+ "keys": [ # A list of specific keys. Entries in `keys` should have exactly as
+ # many elements as there are columns in the primary or index key
+ # with which this `KeySet` is used. Individual key values are
+ # encoded as described here.
+ [
+ "",
+ ],
+ ],
+ "all": True or False, # For convenience `all` can be set to `true` to indicate that this
+ # `KeySet` matches all keys in the table or index. Note that any keys
+ # specified in `keys` or `ranges` are only yielded once.
+ },
+ },
+ "replace": { # Arguments to insert, update, insert_or_update, and # Like insert, except that if the row already exists, it is
+ # deleted, and the column values provided are inserted
+ # instead. Unlike insert_or_update, this means any values not
+ # explicitly written become `NULL`.
+ #
+ # In an interleaved table, if you create the child table with the
+ # `ON DELETE CASCADE` annotation, then replacing a parent row
+ # also deletes the child rows. Otherwise, you must delete the
+ # child rows before you replace the parent row.
+ # replace operations.
+ "table": "A String", # Required. The table whose rows will be written.
+ "values": [ # The values to be written. `values` can contain more than one
+ # list of values. If it does, then multiple rows are written, one
+ # for each entry in `values`. Each list in `values` must have
+ # exactly as many entries as there are entries in columns
+ # above. Sending multiple lists is equivalent to sending multiple
+ # `Mutation`s, each containing one `values` entry and repeating
+ # table and columns. Individual values in each list are
+ # encoded as described here.
+ [
+ "",
+ ],
+ ],
+ "columns": [ # The names of the columns in table to be written.
+ #
+ # The list of columns must contain enough columns to allow
+ # Cloud Spanner to derive values for all primary key columns in the
+ # row(s) to be modified.
+ "A String",
+ ],
+ },
+ "insertOrUpdate": { # Arguments to insert, update, insert_or_update, and # Like insert, except that if the row already exists, then
+ # its column values are overwritten with the ones provided. Any
+ # column values not explicitly written are preserved.
+ #
+ # When using insert_or_update, just as when using insert, all `NOT
+ # NULL` columns in the table must be given a value. This holds true
+ # even when the row already exists and will therefore actually be updated.
+ # replace operations.
+ "table": "A String", # Required. The table whose rows will be written.
+ "values": [ # The values to be written. `values` can contain more than one
+ # list of values. If it does, then multiple rows are written, one
+ # for each entry in `values`. Each list in `values` must have
+ # exactly as many entries as there are entries in columns
+ # above. Sending multiple lists is equivalent to sending multiple
+ # `Mutation`s, each containing one `values` entry and repeating
+ # table and columns. Individual values in each list are
+ # encoded as described here.
+ [
+ "",
+ ],
+ ],
+ "columns": [ # The names of the columns in table to be written.
+ #
+ # The list of columns must contain enough columns to allow
+ # Cloud Spanner to derive values for all primary key columns in the
+ # row(s) to be modified.
+ "A String",
+ ],
+ },
+ "update": { # Arguments to insert, update, insert_or_update, and # Update existing rows in a table. If any of the rows does not
+ # already exist, the transaction fails with error `NOT_FOUND`.
+ # replace operations.
+ "table": "A String", # Required. The table whose rows will be written.
+ "values": [ # The values to be written. `values` can contain more than one
+ # list of values. If it does, then multiple rows are written, one
+ # for each entry in `values`. Each list in `values` must have
+ # exactly as many entries as there are entries in columns
+ # above. Sending multiple lists is equivalent to sending multiple
+ # `Mutation`s, each containing one `values` entry and repeating
+ # table and columns. Individual values in each list are
+ # encoded as described here.
+ [
+ "",
+ ],
+ ],
+ "columns": [ # The names of the columns in table to be written.
+ #
+ # The list of columns must contain enough columns to allow
+ # Cloud Spanner to derive values for all primary key columns in the
+ # row(s) to be modified.
+ "A String",
+ ],
+ },
+ },
+ ],
}
x__xgafv: string, V1 error format.
@@ -1249,11 +1249,9 @@
{ # The request for CreateSession.
"session": { # A session in the Cloud Spanner API. # The session to create.
- "approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is
- # typically earlier than the actual last use time.
+ "createTime": "A String", # Output only. The timestamp when the session is created.
"name": "A String", # The name of the session. This is always system-assigned; values provided
# when creating a session are ignored.
- "createTime": "A String", # Output only. The timestamp when the session is created.
"labels": { # The labels for the session.
#
# * Label keys must be between 1 and 63 characters long and must conform to
@@ -1265,6 +1263,8 @@
# See https://goo.gl/xmQnxf for more information on and examples of labels.
"a_key": "A String",
},
+ "approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is
+ # typically earlier than the actual last use time.
},
}
@@ -1277,11 +1277,9 @@
An object of the form:
{ # A session in the Cloud Spanner API.
- "approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is
- # typically earlier than the actual last use time.
+ "createTime": "A String", # Output only. The timestamp when the session is created.
"name": "A String", # The name of the session. This is always system-assigned; values provided
# when creating a session are ignored.
- "createTime": "A String", # Output only. The timestamp when the session is created.
"labels": { # The labels for the session.
#
# * Label keys must be between 1 and 63 characters long and must conform to
@@ -1293,6 +1291,8 @@
# See https://goo.gl/xmQnxf for more information on and examples of labels.
"a_key": "A String",
},
+ "approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is
+ # typically earlier than the actual last use time.
}</pre>
</div>
@@ -1344,6 +1344,73 @@
The object takes the form of:
{ # The request for ExecuteBatchDml.
+ "statements": [ # Required. The list of statements to execute in this batch. Statements are executed
+ # serially, such that the effects of statement `i` are visible to statement
+ # `i+1`. Each statement must be a DML statement. Execution stops at the
+ # first failed statement; the remaining statements are not executed.
+ #
+ # Callers must provide at least one statement.
+ { # A single DML statement.
+ "params": { # Parameter names and values that bind to placeholders in the DML string.
+ #
+ # A parameter placeholder consists of the `@` character followed by the
+ # parameter name (for example, `@firstName`). Parameter names can contain
+ # letters, numbers, and underscores.
+ #
+ # Parameters can appear anywhere that a literal value is expected. The
+ # same parameter name can be used more than once, for example:
+ #
+ # `"WHERE id > @msg_id AND id < @msg_id + 100"`
+ #
+ # It is an error to execute a SQL statement with unbound parameters.
+ "a_key": "", # Properties of the object.
+ },
+ "sql": "A String", # Required. The DML string.
+ "paramTypes": { # It is not always possible for Cloud Spanner to infer the right SQL type
+ # from a JSON value. For example, values of type `BYTES` and values
+ # of type `STRING` both appear in params as JSON strings.
+ #
+ # In these cases, `param_types` can be used to specify the exact
+ # SQL type for some or all of the SQL statement parameters. See the
+ # definition of Type for more information
+ # about SQL types.
+ "a_key": { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a
+ # table cell or returned from an SQL query.
+ "arrayElementType": # Object with schema name: Type # If code == ARRAY, then `array_element_type`
+ # is the type of the array elements.
+ "code": "A String", # Required. The TypeCode for this type.
+ "structType": { # `StructType` defines the fields of a STRUCT type. # If code == STRUCT, then `struct_type`
+ # provides type information for the struct's fields.
+ "fields": [ # The list of fields that make up this struct. Order is
+ # significant, because values of this struct type are represented as
+ # lists, where the order of field values matches the order of
+ # fields in the StructType. In turn, the order of fields
+ # matches the order of columns in a read request, or the order of
+ # fields in the `SELECT` clause of a query.
+ { # Message representing a single field of a struct.
+ "name": "A String", # The name of the field. For reads, this is the column name. For
+ # SQL queries, it is the column alias (e.g., `"Word"` in the
+ # query `"SELECT 'hello' AS Word"`), or the column name (e.g.,
+ # `"ColName"` in the query `"SELECT ColName FROM Table"`). Some
+ # columns might have an empty name (e.g., !"SELECT
+ # UPPER(ColName)"`). Note that a query result can contain
+ # multiple fields with the same name.
+ "type": # Object with schema name: Type # The type of the field.
+ },
+ ],
+ },
+ },
+ },
+ },
+ ],
+ "seqno": "A String", # Required. A per-transaction sequence number used to identify this request. This field
+ # makes each request idempotent such that if the request is received multiple
+ # times, at most one will succeed.
+ #
+ # The sequence number must be monotonically increasing within the
+ # transaction. If a request arrives for the first time with an out-of-order
+ # sequence number, the transaction may be aborted. Replays of previously
+ # handled requests will yield the same response as the first execution.
"transaction": { # This message is used to select the transaction in which a # Required. The transaction to use. Must be a read-write transaction.
#
# To protect against replays, single-use transactions are not supported. The
@@ -1353,355 +1420,7 @@
# ExecuteSql call runs.
#
# See TransactionOptions for more information about transactions.
- "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
- # This is the most efficient way to execute a transaction that
- # consists of a single SQL query.
- #
- #
- # Each session can have at most one active transaction at a time. After the
- # active transaction is completed, the session can immediately be
- # re-used for the next transaction. It is not necessary to create a
- # new session for each transaction.
- #
- # # Transaction Modes
- #
- # Cloud Spanner supports three transaction modes:
- #
- # 1. Locking read-write. This type of transaction is the only way
- # to write data into Cloud Spanner. These transactions rely on
- # pessimistic locking and, if necessary, two-phase commit.
- # Locking read-write transactions may abort, requiring the
- # application to retry.
- #
- # 2. Snapshot read-only. 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. Snapshot read-only
- # transactions do not need to be committed.
- #
- # 3. Partitioned DML. This type of transaction is used to execute
- # a single Partitioned DML statement. Partitioned DML partitions
- # the key space and runs the DML statement over each partition
- # in parallel using separate, internal transactions that commit
- # independently. Partitioned DML transactions do not need to be
- # committed.
- #
- # For transactions that only read, snapshot read-only transactions
- # provide simpler semantics and are almost always faster. In
- # particular, read-only transactions do not take locks, so they do
- # not conflict with read-write transactions. As a consequence of not
- # taking locks, they also do not abort, so retry loops are not needed.
- #
- # Transactions may only read/write data in a single database. They
- # may, however, read/write data in different tables within that
- # database.
- #
- # ## Locking Read-Write Transactions
- #
- # Locking transactions may be used to atomically read-modify-write
- # data anywhere in a database. This type of transaction is externally
- # consistent.
- #
- # Clients should attempt to minimize the amount of time a transaction
- # is active. Faster transactions commit with higher probability
- # and cause less contention. Cloud Spanner attempts to keep read locks
- # active as long as the transaction continues to do reads, and the
- # transaction has not been terminated by
- # Commit or
- # Rollback. Long periods of
- # inactivity at the client may cause Cloud Spanner to release a
- # transaction's locks and abort it.
- #
- # Conceptually, a read-write transaction consists of zero or more
- # reads or SQL statements followed by
- # Commit. At any time before
- # Commit, the client can send a
- # Rollback request to abort the
- # transaction.
- #
- # ### Semantics
- #
- # Cloud Spanner can commit the transaction if all read locks it acquired
- # are still valid at commit time, and it is able to acquire write
- # locks for all writes. Cloud Spanner can abort the transaction for any
- # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
- # that the transaction has not modified any user data in Cloud Spanner.
- #
- # Unless the transaction commits, Cloud Spanner makes no guarantees about
- # how long the transaction's locks were held for. It is an error to
- # use Cloud Spanner locks for any sort of mutual exclusion other than
- # between Cloud Spanner transactions themselves.
- #
- # ### Retrying Aborted Transactions
- #
- # When a transaction aborts, the application can choose to retry the
- # whole transaction again. To maximize the chances of successfully
- # committing the retry, the client should execute the retry in the
- # same session as the original attempt. The original session's lock
- # priority increases with each consecutive abort, meaning that each
- # attempt has a slightly better chance of success than the previous.
- #
- # Under some circumstances (e.g., many transactions attempting to
- # modify the same row(s)), a transaction can abort many times in a
- # short period before successfully committing. Thus, it is not a good
- # idea to cap the number of retries a transaction can attempt;
- # instead, it is better to limit the total amount of wall time spent
- # retrying.
- #
- # ### Idle Transactions
- #
- # A transaction is considered idle if it has no outstanding reads or
- # SQL queries and has not started a read or SQL query within the last 10
- # seconds. Idle transactions can be aborted by Cloud Spanner so that they
- # don't hold on to locks indefinitely. In that case, the commit will
- # fail with error `ABORTED`.
- #
- # If this behavior is undesirable, periodically executing a simple
- # SQL query in the transaction (e.g., `SELECT 1`) prevents the
- # transaction from becoming idle.
- #
- # ## Snapshot Read-Only Transactions
- #
- # Snapshot read-only transactions provides a simpler method than
- # locking read-write transactions for doing several consistent
- # reads. However, this type of transaction does not support writes.
- #
- # Snapshot transactions do not take locks. Instead, they work by
- # choosing a Cloud Spanner timestamp, then executing all reads at that
- # timestamp. Since they do not acquire locks, they do not block
- # concurrent read-write transactions.
- #
- # Unlike locking read-write transactions, snapshot read-only
- # transactions never abort. They can fail if the chosen read
- # timestamp is garbage collected; however, the default garbage
- # collection policy is generous enough that most applications do not
- # need to worry about this in practice.
- #
- # Snapshot read-only transactions do not need to call
- # Commit or
- # Rollback (and in fact are not
- # permitted to do so).
- #
- # To execute a snapshot transaction, the client specifies a timestamp
- # bound, which tells Cloud Spanner how to choose a read timestamp.
- #
- # The types of timestamp bound are:
- #
- # - Strong (the default).
- # - Bounded staleness.
- # - Exact staleness.
- #
- # If the Cloud Spanner database to be read is geographically distributed,
- # stale read-only transactions can execute more quickly than strong
- # or read-write transaction, because they are able to execute far
- # from the leader replica.
- #
- # Each type of timestamp bound is discussed in detail below.
- #
- # ### Strong
- #
- # Strong reads are guaranteed to see the effects of all transactions
- # that have committed before the start of the read. Furthermore, all
- # rows yielded by a single read are consistent with each other -- if
- # any part of the read observes a transaction, all parts of the read
- # see the transaction.
- #
- # Strong reads are not repeatable: two consecutive strong read-only
- # transactions might return inconsistent results if there are
- # concurrent writes. If consistency across reads is required, the
- # reads should be executed within a transaction or at an exact read
- # timestamp.
- #
- # See TransactionOptions.ReadOnly.strong.
- #
- # ### Exact Staleness
- #
- # These timestamp bounds execute reads at a user-specified
- # timestamp. Reads at a timestamp are guaranteed to see a consistent
- # prefix of the global transaction history: they observe
- # modifications done by all transactions with a commit timestamp <=
- # the read timestamp, and observe none of the modifications done by
- # transactions with a larger commit timestamp. They will block until
- # all conflicting transactions that may be assigned commit timestamps
- # <= the read timestamp have finished.
- #
- # The timestamp can either be expressed as an absolute Cloud Spanner commit
- # timestamp or a staleness relative to the current time.
- #
- # These modes do not require a "negotiation phase" to pick a
- # timestamp. As a result, they execute slightly faster than the
- # equivalent boundedly stale concurrency modes. On the other hand,
- # boundedly stale reads usually return fresher results.
- #
- # See TransactionOptions.ReadOnly.read_timestamp and
- # TransactionOptions.ReadOnly.exact_staleness.
- #
- # ### Bounded Staleness
- #
- # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
- # subject to a user-provided staleness bound. Cloud Spanner chooses the
- # newest timestamp within the staleness bound that allows execution
- # of the reads at the closest available replica without blocking.
- #
- # All rows yielded are consistent with each other -- if any part of
- # the read observes a transaction, all parts of the read see the
- # transaction. Boundedly stale reads are not repeatable: two stale
- # reads, even if they use the same staleness bound, can execute at
- # different timestamps and thus return inconsistent results.
- #
- # Boundedly stale reads execute in two phases: the first phase
- # negotiates a timestamp among all replicas needed to serve the
- # read. In the second phase, reads are executed at the negotiated
- # timestamp.
- #
- # As a result of the two phase execution, bounded staleness reads are
- # usually a little slower than comparable exact staleness
- # reads. However, they are typically able to return fresher
- # results, and are more likely to execute at the closest replica.
- #
- # Because the timestamp negotiation requires up-front knowledge of
- # which rows will be read, it can only be used with single-use
- # read-only transactions.
- #
- # See TransactionOptions.ReadOnly.max_staleness and
- # TransactionOptions.ReadOnly.min_read_timestamp.
- #
- # ### Old Read Timestamps and Garbage Collection
- #
- # Cloud Spanner continuously garbage collects deleted and overwritten data
- # in the background to reclaim storage space. This process is known
- # as "version GC". By default, version GC reclaims versions after they
- # are one hour old. Because of this, Cloud Spanner cannot perform reads
- # at read timestamps more than one hour in the past. This
- # restriction also applies to in-progress reads and/or SQL queries whose
- # timestamp become too old while executing. Reads and SQL queries with
- # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
- #
- # ## Partitioned DML Transactions
- #
- # Partitioned DML transactions are used to execute DML statements with a
- # different execution strategy that provides different, and often better,
- # scalability properties for large, table-wide operations than DML in a
- # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
- # should prefer using ReadWrite transactions.
- #
- # Partitioned DML partitions the keyspace and runs the DML statement on each
- # partition in separate, internal transactions. These transactions commit
- # automatically when complete, and run independently from one another.
- #
- # To reduce lock contention, this execution strategy only acquires read locks
- # on rows that match the WHERE clause of the statement. Additionally, the
- # smaller per-partition transactions hold locks for less time.
- #
- # That said, Partitioned DML is not a drop-in replacement for standard DML used
- # in ReadWrite transactions.
- #
- # - The DML statement must be fully-partitionable. Specifically, the statement
- # must be expressible as the union of many statements which each access only
- # a single row of the table.
- #
- # - The statement is not applied atomically to all rows of the table. Rather,
- # the statement is applied atomically to partitions of the table, in
- # independent transactions. Secondary index rows are updated atomically
- # with the base table rows.
- #
- # - Partitioned DML does not guarantee exactly-once execution semantics
- # against a partition. The statement will be applied at least once to each
- # partition. It is strongly recommended that the DML statement should be
- # idempotent to avoid unexpected results. For instance, it is potentially
- # dangerous to run a statement such as
- # `UPDATE table SET column = column + 1` as it could be run multiple times
- # against some rows.
- #
- # - The partitions are committed automatically - there is no support for
- # Commit or Rollback. If the call returns an error, or if the client issuing
- # the ExecuteSql call dies, it is possible that some rows had the statement
- # executed on them successfully. It is also possible that statement was
- # never executed against other rows.
- #
- # - Partitioned DML transactions may only contain the execution of a single
- # DML statement via ExecuteSql or ExecuteStreamingSql.
- #
- # - If any error is encountered during the execution of the partitioned DML
- # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
- # value that cannot be stored due to schema constraints), then the
- # operation is stopped at that point and an error is returned. It is
- # possible that at this point, some partitions have been committed (or even
- # committed multiple times), and other partitions have not been run at all.
- #
- # Given the above, Partitioned DML is good fit for large, database-wide,
- # operations that are idempotent, such as deleting old rows from a very large
- # table.
- "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
- #
- # Authorization to begin a Partitioned DML transaction requires
- # `spanner.databases.beginPartitionedDmlTransaction` permission
- # on the `session` resource.
- },
- "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
- #
- # Authorization to begin a read-only transaction requires
- # `spanner.databases.beginReadOnlyTransaction` permission
- # on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
- # seconds. Guarantees that all writes that have committed more
- # than the specified number of seconds ago are visible. Because
- # Cloud Spanner chooses the exact timestamp, this mode works even if
- # the client's local clock is substantially skewed from Cloud Spanner
- # commit timestamps.
- #
- # Useful for reading the freshest data available at a nearby
- # replica, while bounding the possible staleness if the local
- # replica has fallen behind.
- #
- # Note that this option can only be used in single-use
- # transactions.
- "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
- # the Transaction message that describes the transaction.
- "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
- # old. The timestamp is chosen soon after the read is started.
- #
- # Guarantees that all writes that have committed more than the
- # specified number of seconds ago are visible. Because Cloud Spanner
- # chooses the exact timestamp, this mode works even if the client's
- # local clock is substantially skewed from Cloud Spanner commit
- # timestamps.
- #
- # Useful for reading at nearby replicas without the distributed
- # timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
- },
- "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
- #
- # Authorization to begin a read-write transaction requires
- # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
- # on the `session` resource.
- # transaction type has no options.
- },
- },
+ "id": "A String", # Execute the read or SQL query in a previously-started transaction.
"begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in
# it. The transaction ID of the new transaction is returned in
# ResultSetMetadata.transaction, which is a Transaction.
@@ -1987,33 +1706,18 @@
# `spanner.databases.beginPartitionedDmlTransaction` permission
# on the `session` resource.
},
+ "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
+ #
+ # Authorization to begin a read-write transaction requires
+ # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
+ # on the `session` resource.
+ # transaction type has no options.
+ },
"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
#
# Authorization to begin a read-only transaction requires
# `spanner.databases.beginReadOnlyTransaction` permission
# on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
# seconds. Guarantees that all writes that have committed more
# than the specified number of seconds ago are visible. Because
@@ -2027,6 +1731,18 @@
#
# Note that this option can only be used in single-use
# transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
# the Transaction message that describes the transaction.
"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
@@ -2040,8 +1756,304 @@
#
# Useful for reading at nearby replicas without the distributed
# timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
+ },
+ "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
+ # This is the most efficient way to execute a transaction that
+ # consists of a single SQL query.
+ #
+ #
+ # Each session can have at most one active transaction at a time. After the
+ # active transaction is completed, the session can immediately be
+ # re-used for the next transaction. It is not necessary to create a
+ # new session for each transaction.
+ #
+ # # Transaction Modes
+ #
+ # Cloud Spanner supports three transaction modes:
+ #
+ # 1. Locking read-write. This type of transaction is the only way
+ # to write data into Cloud Spanner. These transactions rely on
+ # pessimistic locking and, if necessary, two-phase commit.
+ # Locking read-write transactions may abort, requiring the
+ # application to retry.
+ #
+ # 2. Snapshot read-only. 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. Snapshot read-only
+ # transactions do not need to be committed.
+ #
+ # 3. Partitioned DML. This type of transaction is used to execute
+ # a single Partitioned DML statement. Partitioned DML partitions
+ # the key space and runs the DML statement over each partition
+ # in parallel using separate, internal transactions that commit
+ # independently. Partitioned DML transactions do not need to be
+ # committed.
+ #
+ # For transactions that only read, snapshot read-only transactions
+ # provide simpler semantics and are almost always faster. In
+ # particular, read-only transactions do not take locks, so they do
+ # not conflict with read-write transactions. As a consequence of not
+ # taking locks, they also do not abort, so retry loops are not needed.
+ #
+ # Transactions may only read/write data in a single database. They
+ # may, however, read/write data in different tables within that
+ # database.
+ #
+ # ## Locking Read-Write Transactions
+ #
+ # Locking transactions may be used to atomically read-modify-write
+ # data anywhere in a database. This type of transaction is externally
+ # consistent.
+ #
+ # Clients should attempt to minimize the amount of time a transaction
+ # is active. Faster transactions commit with higher probability
+ # and cause less contention. Cloud Spanner attempts to keep read locks
+ # active as long as the transaction continues to do reads, and the
+ # transaction has not been terminated by
+ # Commit or
+ # Rollback. Long periods of
+ # inactivity at the client may cause Cloud Spanner to release a
+ # transaction's locks and abort it.
+ #
+ # Conceptually, a read-write transaction consists of zero or more
+ # reads or SQL statements followed by
+ # Commit. At any time before
+ # Commit, the client can send a
+ # Rollback request to abort the
+ # transaction.
+ #
+ # ### Semantics
+ #
+ # Cloud Spanner can commit the transaction if all read locks it acquired
+ # are still valid at commit time, and it is able to acquire write
+ # locks for all writes. Cloud Spanner can abort the transaction for any
+ # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
+ # that the transaction has not modified any user data in Cloud Spanner.
+ #
+ # Unless the transaction commits, Cloud Spanner makes no guarantees about
+ # how long the transaction's locks were held for. It is an error to
+ # use Cloud Spanner locks for any sort of mutual exclusion other than
+ # between Cloud Spanner transactions themselves.
+ #
+ # ### Retrying Aborted Transactions
+ #
+ # When a transaction aborts, the application can choose to retry the
+ # whole transaction again. To maximize the chances of successfully
+ # committing the retry, the client should execute the retry in the
+ # same session as the original attempt. The original session's lock
+ # priority increases with each consecutive abort, meaning that each
+ # attempt has a slightly better chance of success than the previous.
+ #
+ # Under some circumstances (e.g., many transactions attempting to
+ # modify the same row(s)), a transaction can abort many times in a
+ # short period before successfully committing. Thus, it is not a good
+ # idea to cap the number of retries a transaction can attempt;
+ # instead, it is better to limit the total amount of wall time spent
+ # retrying.
+ #
+ # ### Idle Transactions
+ #
+ # A transaction is considered idle if it has no outstanding reads or
+ # SQL queries and has not started a read or SQL query within the last 10
+ # seconds. Idle transactions can be aborted by Cloud Spanner so that they
+ # don't hold on to locks indefinitely. In that case, the commit will
+ # fail with error `ABORTED`.
+ #
+ # If this behavior is undesirable, periodically executing a simple
+ # SQL query in the transaction (e.g., `SELECT 1`) prevents the
+ # transaction from becoming idle.
+ #
+ # ## Snapshot Read-Only Transactions
+ #
+ # Snapshot read-only transactions provides a simpler method than
+ # locking read-write transactions for doing several consistent
+ # reads. However, this type of transaction does not support writes.
+ #
+ # Snapshot transactions do not take locks. Instead, they work by
+ # choosing a Cloud Spanner timestamp, then executing all reads at that
+ # timestamp. Since they do not acquire locks, they do not block
+ # concurrent read-write transactions.
+ #
+ # Unlike locking read-write transactions, snapshot read-only
+ # transactions never abort. They can fail if the chosen read
+ # timestamp is garbage collected; however, the default garbage
+ # collection policy is generous enough that most applications do not
+ # need to worry about this in practice.
+ #
+ # Snapshot read-only transactions do not need to call
+ # Commit or
+ # Rollback (and in fact are not
+ # permitted to do so).
+ #
+ # To execute a snapshot transaction, the client specifies a timestamp
+ # bound, which tells Cloud Spanner how to choose a read timestamp.
+ #
+ # The types of timestamp bound are:
+ #
+ # - Strong (the default).
+ # - Bounded staleness.
+ # - Exact staleness.
+ #
+ # If the Cloud Spanner database to be read is geographically distributed,
+ # stale read-only transactions can execute more quickly than strong
+ # or read-write transaction, because they are able to execute far
+ # from the leader replica.
+ #
+ # Each type of timestamp bound is discussed in detail below.
+ #
+ # ### Strong
+ #
+ # Strong reads are guaranteed to see the effects of all transactions
+ # that have committed before the start of the read. Furthermore, all
+ # rows yielded by a single read are consistent with each other -- if
+ # any part of the read observes a transaction, all parts of the read
+ # see the transaction.
+ #
+ # Strong reads are not repeatable: two consecutive strong read-only
+ # transactions might return inconsistent results if there are
+ # concurrent writes. If consistency across reads is required, the
+ # reads should be executed within a transaction or at an exact read
+ # timestamp.
+ #
+ # See TransactionOptions.ReadOnly.strong.
+ #
+ # ### Exact Staleness
+ #
+ # These timestamp bounds execute reads at a user-specified
+ # timestamp. Reads at a timestamp are guaranteed to see a consistent
+ # prefix of the global transaction history: they observe
+ # modifications done by all transactions with a commit timestamp <=
+ # the read timestamp, and observe none of the modifications done by
+ # transactions with a larger commit timestamp. They will block until
+ # all conflicting transactions that may be assigned commit timestamps
+ # <= the read timestamp have finished.
+ #
+ # The timestamp can either be expressed as an absolute Cloud Spanner commit
+ # timestamp or a staleness relative to the current time.
+ #
+ # These modes do not require a "negotiation phase" to pick a
+ # timestamp. As a result, they execute slightly faster than the
+ # equivalent boundedly stale concurrency modes. On the other hand,
+ # boundedly stale reads usually return fresher results.
+ #
+ # See TransactionOptions.ReadOnly.read_timestamp and
+ # TransactionOptions.ReadOnly.exact_staleness.
+ #
+ # ### Bounded Staleness
+ #
+ # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
+ # subject to a user-provided staleness bound. Cloud Spanner chooses the
+ # newest timestamp within the staleness bound that allows execution
+ # of the reads at the closest available replica without blocking.
+ #
+ # All rows yielded are consistent with each other -- if any part of
+ # the read observes a transaction, all parts of the read see the
+ # transaction. Boundedly stale reads are not repeatable: two stale
+ # reads, even if they use the same staleness bound, can execute at
+ # different timestamps and thus return inconsistent results.
+ #
+ # Boundedly stale reads execute in two phases: the first phase
+ # negotiates a timestamp among all replicas needed to serve the
+ # read. In the second phase, reads are executed at the negotiated
+ # timestamp.
+ #
+ # As a result of the two phase execution, bounded staleness reads are
+ # usually a little slower than comparable exact staleness
+ # reads. However, they are typically able to return fresher
+ # results, and are more likely to execute at the closest replica.
+ #
+ # Because the timestamp negotiation requires up-front knowledge of
+ # which rows will be read, it can only be used with single-use
+ # read-only transactions.
+ #
+ # See TransactionOptions.ReadOnly.max_staleness and
+ # TransactionOptions.ReadOnly.min_read_timestamp.
+ #
+ # ### Old Read Timestamps and Garbage Collection
+ #
+ # Cloud Spanner continuously garbage collects deleted and overwritten data
+ # in the background to reclaim storage space. This process is known
+ # as "version GC". By default, version GC reclaims versions after they
+ # are one hour old. Because of this, Cloud Spanner cannot perform reads
+ # at read timestamps more than one hour in the past. This
+ # restriction also applies to in-progress reads and/or SQL queries whose
+ # timestamp become too old while executing. Reads and SQL queries with
+ # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
+ #
+ # ## Partitioned DML Transactions
+ #
+ # Partitioned DML transactions are used to execute DML statements with a
+ # different execution strategy that provides different, and often better,
+ # scalability properties for large, table-wide operations than DML in a
+ # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+ # should prefer using ReadWrite transactions.
+ #
+ # Partitioned DML partitions the keyspace and runs the DML statement on each
+ # partition in separate, internal transactions. These transactions commit
+ # automatically when complete, and run independently from one another.
+ #
+ # To reduce lock contention, this execution strategy only acquires read locks
+ # on rows that match the WHERE clause of the statement. Additionally, the
+ # smaller per-partition transactions hold locks for less time.
+ #
+ # That said, Partitioned DML is not a drop-in replacement for standard DML used
+ # in ReadWrite transactions.
+ #
+ # - The DML statement must be fully-partitionable. Specifically, the statement
+ # must be expressible as the union of many statements which each access only
+ # a single row of the table.
+ #
+ # - The statement is not applied atomically to all rows of the table. Rather,
+ # the statement is applied atomically to partitions of the table, in
+ # independent transactions. Secondary index rows are updated atomically
+ # with the base table rows.
+ #
+ # - Partitioned DML does not guarantee exactly-once execution semantics
+ # against a partition. The statement will be applied at least once to each
+ # partition. It is strongly recommended that the DML statement should be
+ # idempotent to avoid unexpected results. For instance, it is potentially
+ # dangerous to run a statement such as
+ # `UPDATE table SET column = column + 1` as it could be run multiple times
+ # against some rows.
+ #
+ # - The partitions are committed automatically - there is no support for
+ # Commit or Rollback. If the call returns an error, or if the client issuing
+ # the ExecuteSql call dies, it is possible that some rows had the statement
+ # executed on them successfully. It is also possible that statement was
+ # never executed against other rows.
+ #
+ # - Partitioned DML transactions may only contain the execution of a single
+ # DML statement via ExecuteSql or ExecuteStreamingSql.
+ #
+ # - If any error is encountered during the execution of the partitioned DML
+ # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
+ # value that cannot be stored due to schema constraints), then the
+ # operation is stopped at that point and an error is returned. It is
+ # possible that at this point, some partitions have been committed (or even
+ # committed multiple times), and other partitions have not been run at all.
+ #
+ # Given the above, Partitioned DML is good fit for large, database-wide,
+ # operations that are idempotent, such as deleting old rows from a very large
+ # table.
+ "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
+ #
+ # Authorization to begin a Partitioned DML transaction requires
+ # `spanner.databases.beginPartitionedDmlTransaction` permission
+ # on the `session` resource.
},
"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
#
@@ -2050,76 +2062,64 @@
# on the `session` resource.
# transaction type has no options.
},
+ "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
+ #
+ # Authorization to begin a read-only transaction requires
+ # `spanner.databases.beginReadOnlyTransaction` permission
+ # on the `session` resource.
+ "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
+ # seconds. Guarantees that all writes that have committed more
+ # than the specified number of seconds ago are visible. Because
+ # Cloud Spanner chooses the exact timestamp, this mode works even if
+ # the client's local clock is substantially skewed from Cloud Spanner
+ # commit timestamps.
+ #
+ # Useful for reading the freshest data available at a nearby
+ # replica, while bounding the possible staleness if the local
+ # replica has fallen behind.
+ #
+ # Note that this option can only be used in single-use
+ # transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
+ "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
+ # the Transaction message that describes the transaction.
+ "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
+ # old. The timestamp is chosen soon after the read is started.
+ #
+ # Guarantees that all writes that have committed more than the
+ # specified number of seconds ago are visible. Because Cloud Spanner
+ # chooses the exact timestamp, this mode works even if the client's
+ # local clock is substantially skewed from Cloud Spanner commit
+ # timestamps.
+ #
+ # Useful for reading at nearby replicas without the distributed
+ # timestamp negotiation overhead of `max_staleness`.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
},
- "id": "A String", # Execute the read or SQL query in a previously-started transaction.
},
- "seqno": "A String", # Required. A per-transaction sequence number used to identify this request. This field
- # makes each request idempotent such that if the request is received multiple
- # times, at most one will succeed.
- #
- # The sequence number must be monotonically increasing within the
- # transaction. If a request arrives for the first time with an out-of-order
- # sequence number, the transaction may be aborted. Replays of previously
- # handled requests will yield the same response as the first execution.
- "statements": [ # Required. The list of statements to execute in this batch. Statements are executed
- # serially, such that the effects of statement `i` are visible to statement
- # `i+1`. Each statement must be a DML statement. Execution stops at the
- # first failed statement; the remaining statements are not executed.
- #
- # Callers must provide at least one statement.
- { # A single DML statement.
- "paramTypes": { # It is not always possible for Cloud Spanner to infer the right SQL type
- # from a JSON value. For example, values of type `BYTES` and values
- # of type `STRING` both appear in params as JSON strings.
- #
- # In these cases, `param_types` can be used to specify the exact
- # SQL type for some or all of the SQL statement parameters. See the
- # definition of Type for more information
- # about SQL types.
- "a_key": { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a
- # table cell or returned from an SQL query.
- "arrayElementType": # Object with schema name: Type # If code == ARRAY, then `array_element_type`
- # is the type of the array elements.
- "code": "A String", # Required. The TypeCode for this type.
- "structType": { # `StructType` defines the fields of a STRUCT type. # If code == STRUCT, then `struct_type`
- # provides type information for the struct's fields.
- "fields": [ # The list of fields that make up this struct. Order is
- # significant, because values of this struct type are represented as
- # lists, where the order of field values matches the order of
- # fields in the StructType. In turn, the order of fields
- # matches the order of columns in a read request, or the order of
- # fields in the `SELECT` clause of a query.
- { # Message representing a single field of a struct.
- "name": "A String", # The name of the field. For reads, this is the column name. For
- # SQL queries, it is the column alias (e.g., `"Word"` in the
- # query `"SELECT 'hello' AS Word"`), or the column name (e.g.,
- # `"ColName"` in the query `"SELECT ColName FROM Table"`). Some
- # columns might have an empty name (e.g., !"SELECT
- # UPPER(ColName)"`). Note that a query result can contain
- # multiple fields with the same name.
- "type": # Object with schema name: Type # The type of the field.
- },
- ],
- },
- },
- },
- "sql": "A String", # Required. The DML string.
- "params": { # Parameter names and values that bind to placeholders in the DML string.
- #
- # A parameter placeholder consists of the `@` character followed by the
- # parameter name (for example, `@firstName`). Parameter names can contain
- # letters, numbers, and underscores.
- #
- # Parameters can appear anywhere that a literal value is expected. The
- # same parameter name can be used more than once, for example:
- #
- # `"WHERE id > @msg_id AND id < @msg_id + 100"`
- #
- # It is an error to execute a SQL statement with unbound parameters.
- "a_key": "", # Properties of the object.
- },
- },
- ],
}
x__xgafv: string, V1 error format.
@@ -2162,16 +2162,16 @@
#
# You can find out more about this error model and how to work with it in the
# [API Design Guide](https://cloud.google.com/apis/design/errors).
- "code": 42, # The status code, which should be an enum value of google.rpc.Code.
- "message": "A String", # A developer-facing error message, which should be in English. Any
- # user-facing error message should be localized and sent in the
- # google.rpc.Status.details field, or localized by the client.
"details": [ # A list of messages that carry the error details. There is a common set of
# message types for APIs to use.
{
"a_key": "", # Properties of the object. Contains field @type with type URL.
},
],
+ "message": "A String", # A developer-facing error message, which should be in English. Any
+ # user-facing error message should be localized and sent in the
+ # google.rpc.Status.details field, or localized by the client.
+ "code": 42, # The status code, which should be an enum value of google.rpc.Code.
},
"resultSets": [ # One ResultSet for each statement in the request that ran successfully,
# in the same order as the statements in the request. Each ResultSet does
@@ -2182,99 +2182,6 @@
# ResultSetMetadata.
{ # Results from Read or
# ExecuteSql.
- "stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the SQL statement that
- # produced this result set. These can be requested by setting
- # ExecuteSqlRequest.query_mode.
- # DML statements always produce stats containing the number of rows
- # modified, unless executed using the
- # ExecuteSqlRequest.QueryMode.PLAN ExecuteSqlRequest.query_mode.
- # Other fields may or may not be populated, based on the
- # ExecuteSqlRequest.query_mode.
- "rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.
- "queryStats": { # Aggregated statistics from the execution of the query. Only present when
- # the query is profiled. For example, a query could return the statistics as
- # follows:
- #
- # {
- # "rows_returned": "3",
- # "elapsed_time": "1.22 secs",
- # "cpu_time": "1.19 secs"
- # }
- "a_key": "", # Properties of the object.
- },
- "rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it
- # returns a lower bound of the rows modified.
- "queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
- "planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
- # with the plan root. Each PlanNode's `id` corresponds to its index in
- # `plan_nodes`.
- { # Node information for nodes appearing in a QueryPlan.plan_nodes.
- "metadata": { # Attributes relevant to the node contained in a group of key-value pairs.
- # For example, a Parameter Reference node could have the following
- # information in its metadata:
- #
- # {
- # "parameter_reference": "param1",
- # "parameter_type": "array"
- # }
- "a_key": "", # Properties of the object.
- },
- "executionStats": { # The execution statistics associated with the node, contained in a group of
- # key-value pairs. Only present if the plan was returned as a result of a
- # profile query. For example, number of executions, number of rows/time per
- # execution etc.
- "a_key": "", # Properties of the object.
- },
- "shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
- # `SCALAR` PlanNode(s).
- "description": "A String", # A string representation of the expression subtree rooted at this node.
- "subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases
- # where the `description` string of this node references a `SCALAR`
- # subquery contained in the expression subtree rooted at this node. The
- # referenced `SCALAR` subquery may not necessarily be a direct child of
- # this node.
- "a_key": 42,
- },
- },
- "index": 42, # The `PlanNode`'s index in node list.
- "kind": "A String", # Used to determine the type of node. May be needed for visualizing
- # different kinds of nodes differently. For example, If the node is a
- # SCALAR node, it will have a condensed representation
- # which can be used to directly embed a description of the node in its
- # parent.
- "displayName": "A String", # The display name for the node.
- "childLinks": [ # List of child node `index`es and their relationship to this parent.
- { # Metadata associated with a parent-child relationship appearing in a
- # PlanNode.
- "variable": "A String", # Only present if the child node is SCALAR and corresponds
- # to an output variable of the parent node. The field carries the name of
- # the output variable.
- # For example, a `TableScan` operator that reads rows from a table will
- # have child links to the `SCALAR` nodes representing the output variables
- # created for each column that is read by the operator. The corresponding
- # `variable` fields will be set to the variable names assigned to the
- # columns.
- "childIndex": 42, # The node to which the link points.
- "type": "A String", # The type of the link. For example, in Hash Joins this could be used to
- # distinguish between the build child and the probe child, or in the case
- # of the child being an output variable, to represent the tag associated
- # with the output variable.
- },
- ],
- },
- ],
- },
- },
- "rows": [ # Each element in `rows` is a row whose format is defined by
- # metadata.row_type. The ith element
- # in each row matches the ith field in
- # metadata.row_type. Elements are
- # encoded based on type as described
- # here.
- [
- "",
- ],
- ],
"metadata": { # Metadata about a ResultSet or PartialResultSet. # Metadata about the result set, such as row type information.
"rowType": { # `StructType` defines the fields of a STRUCT type. # Indicates the field names and types for the rows in the result
# set. For example, a SQL query like `"SELECT UserId, UserName FROM
@@ -2304,6 +2211,12 @@
},
"transaction": { # A transaction. # If the read or SQL query began a transaction as a side-effect, the
# information about the new transaction is yielded here.
+ "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
+ # for the transaction. Not returned by default: see
+ # TransactionOptions.ReadOnly.return_read_timestamp.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
"id": "A String", # `id` may be used to identify the transaction in subsequent
# Read,
# ExecuteSql,
@@ -2312,14 +2225,101 @@
#
# Single-use read-only transactions do not have IDs, because
# single-use transactions do not support multiple requests.
- "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
- # for the transaction. Not returned by default: see
- # TransactionOptions.ReadOnly.return_read_timestamp.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
},
},
+ "stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the SQL statement that
+ # produced this result set. These can be requested by setting
+ # ExecuteSqlRequest.query_mode.
+ # DML statements always produce stats containing the number of rows
+ # modified, unless executed using the
+ # ExecuteSqlRequest.QueryMode.PLAN ExecuteSqlRequest.query_mode.
+ # Other fields may or may not be populated, based on the
+ # ExecuteSqlRequest.query_mode.
+ "rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it
+ # returns a lower bound of the rows modified.
+ "queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
+ "planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
+ # with the plan root. Each PlanNode's `id` corresponds to its index in
+ # `plan_nodes`.
+ { # Node information for nodes appearing in a QueryPlan.plan_nodes.
+ "displayName": "A String", # The display name for the node.
+ "executionStats": { # The execution statistics associated with the node, contained in a group of
+ # key-value pairs. Only present if the plan was returned as a result of a
+ # profile query. For example, number of executions, number of rows/time per
+ # execution etc.
+ "a_key": "", # Properties of the object.
+ },
+ "shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
+ # `SCALAR` PlanNode(s).
+ "subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases
+ # where the `description` string of this node references a `SCALAR`
+ # subquery contained in the expression subtree rooted at this node. The
+ # referenced `SCALAR` subquery may not necessarily be a direct child of
+ # this node.
+ "a_key": 42,
+ },
+ "description": "A String", # A string representation of the expression subtree rooted at this node.
+ },
+ "metadata": { # Attributes relevant to the node contained in a group of key-value pairs.
+ # For example, a Parameter Reference node could have the following
+ # information in its metadata:
+ #
+ # {
+ # "parameter_reference": "param1",
+ # "parameter_type": "array"
+ # }
+ "a_key": "", # Properties of the object.
+ },
+ "childLinks": [ # List of child node `index`es and their relationship to this parent.
+ { # Metadata associated with a parent-child relationship appearing in a
+ # PlanNode.
+ "type": "A String", # The type of the link. For example, in Hash Joins this could be used to
+ # distinguish between the build child and the probe child, or in the case
+ # of the child being an output variable, to represent the tag associated
+ # with the output variable.
+ "variable": "A String", # Only present if the child node is SCALAR and corresponds
+ # to an output variable of the parent node. The field carries the name of
+ # the output variable.
+ # For example, a `TableScan` operator that reads rows from a table will
+ # have child links to the `SCALAR` nodes representing the output variables
+ # created for each column that is read by the operator. The corresponding
+ # `variable` fields will be set to the variable names assigned to the
+ # columns.
+ "childIndex": 42, # The node to which the link points.
+ },
+ ],
+ "index": 42, # The `PlanNode`'s index in node list.
+ "kind": "A String", # Used to determine the type of node. May be needed for visualizing
+ # different kinds of nodes differently. For example, If the node is a
+ # SCALAR node, it will have a condensed representation
+ # which can be used to directly embed a description of the node in its
+ # parent.
+ },
+ ],
+ },
+ "rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.
+ "queryStats": { # Aggregated statistics from the execution of the query. Only present when
+ # the query is profiled. For example, a query could return the statistics as
+ # follows:
+ #
+ # {
+ # "rows_returned": "3",
+ # "elapsed_time": "1.22 secs",
+ # "cpu_time": "1.19 secs"
+ # }
+ "a_key": "", # Properties of the object.
+ },
+ },
+ "rows": [ # Each element in `rows` is a row whose format is defined by
+ # metadata.row_type. The ith element
+ # in each row matches the ith field in
+ # metadata.row_type. Elements are
+ # encoded based on type as described
+ # here.
+ [
+ "",
+ ],
+ ],
},
],
}</pre>
@@ -2346,9 +2346,16 @@
{ # The request for ExecuteSql and
# ExecuteStreamingSql.
- "queryMode": "A String", # Used to control the amount of debugging information returned in
- # ResultSetStats. If partition_token is set, query_mode can only
- # be set to QueryMode.NORMAL.
+ "seqno": "A String", # A per-transaction sequence number used to identify this request. This field
+ # makes each request idempotent such that if the request is received multiple
+ # times, at most one will succeed.
+ #
+ # The sequence number must be monotonically increasing within the
+ # transaction. If a request arrives for the first time with an out-of-order
+ # sequence number, the transaction may be aborted. Replays of previously
+ # handled requests will yield the same response as the first execution.
+ #
+ # Required for DML statements. Ignored for queries.
"transaction": { # This message is used to select the transaction in which a # The transaction to use.
#
# For queries, if none is provided, the default is a temporary read-only
@@ -2363,355 +2370,7 @@
# ExecuteSql call runs.
#
# See TransactionOptions for more information about transactions.
- "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
- # This is the most efficient way to execute a transaction that
- # consists of a single SQL query.
- #
- #
- # Each session can have at most one active transaction at a time. After the
- # active transaction is completed, the session can immediately be
- # re-used for the next transaction. It is not necessary to create a
- # new session for each transaction.
- #
- # # Transaction Modes
- #
- # Cloud Spanner supports three transaction modes:
- #
- # 1. Locking read-write. This type of transaction is the only way
- # to write data into Cloud Spanner. These transactions rely on
- # pessimistic locking and, if necessary, two-phase commit.
- # Locking read-write transactions may abort, requiring the
- # application to retry.
- #
- # 2. Snapshot read-only. 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. Snapshot read-only
- # transactions do not need to be committed.
- #
- # 3. Partitioned DML. This type of transaction is used to execute
- # a single Partitioned DML statement. Partitioned DML partitions
- # the key space and runs the DML statement over each partition
- # in parallel using separate, internal transactions that commit
- # independently. Partitioned DML transactions do not need to be
- # committed.
- #
- # For transactions that only read, snapshot read-only transactions
- # provide simpler semantics and are almost always faster. In
- # particular, read-only transactions do not take locks, so they do
- # not conflict with read-write transactions. As a consequence of not
- # taking locks, they also do not abort, so retry loops are not needed.
- #
- # Transactions may only read/write data in a single database. They
- # may, however, read/write data in different tables within that
- # database.
- #
- # ## Locking Read-Write Transactions
- #
- # Locking transactions may be used to atomically read-modify-write
- # data anywhere in a database. This type of transaction is externally
- # consistent.
- #
- # Clients should attempt to minimize the amount of time a transaction
- # is active. Faster transactions commit with higher probability
- # and cause less contention. Cloud Spanner attempts to keep read locks
- # active as long as the transaction continues to do reads, and the
- # transaction has not been terminated by
- # Commit or
- # Rollback. Long periods of
- # inactivity at the client may cause Cloud Spanner to release a
- # transaction's locks and abort it.
- #
- # Conceptually, a read-write transaction consists of zero or more
- # reads or SQL statements followed by
- # Commit. At any time before
- # Commit, the client can send a
- # Rollback request to abort the
- # transaction.
- #
- # ### Semantics
- #
- # Cloud Spanner can commit the transaction if all read locks it acquired
- # are still valid at commit time, and it is able to acquire write
- # locks for all writes. Cloud Spanner can abort the transaction for any
- # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
- # that the transaction has not modified any user data in Cloud Spanner.
- #
- # Unless the transaction commits, Cloud Spanner makes no guarantees about
- # how long the transaction's locks were held for. It is an error to
- # use Cloud Spanner locks for any sort of mutual exclusion other than
- # between Cloud Spanner transactions themselves.
- #
- # ### Retrying Aborted Transactions
- #
- # When a transaction aborts, the application can choose to retry the
- # whole transaction again. To maximize the chances of successfully
- # committing the retry, the client should execute the retry in the
- # same session as the original attempt. The original session's lock
- # priority increases with each consecutive abort, meaning that each
- # attempt has a slightly better chance of success than the previous.
- #
- # Under some circumstances (e.g., many transactions attempting to
- # modify the same row(s)), a transaction can abort many times in a
- # short period before successfully committing. Thus, it is not a good
- # idea to cap the number of retries a transaction can attempt;
- # instead, it is better to limit the total amount of wall time spent
- # retrying.
- #
- # ### Idle Transactions
- #
- # A transaction is considered idle if it has no outstanding reads or
- # SQL queries and has not started a read or SQL query within the last 10
- # seconds. Idle transactions can be aborted by Cloud Spanner so that they
- # don't hold on to locks indefinitely. In that case, the commit will
- # fail with error `ABORTED`.
- #
- # If this behavior is undesirable, periodically executing a simple
- # SQL query in the transaction (e.g., `SELECT 1`) prevents the
- # transaction from becoming idle.
- #
- # ## Snapshot Read-Only Transactions
- #
- # Snapshot read-only transactions provides a simpler method than
- # locking read-write transactions for doing several consistent
- # reads. However, this type of transaction does not support writes.
- #
- # Snapshot transactions do not take locks. Instead, they work by
- # choosing a Cloud Spanner timestamp, then executing all reads at that
- # timestamp. Since they do not acquire locks, they do not block
- # concurrent read-write transactions.
- #
- # Unlike locking read-write transactions, snapshot read-only
- # transactions never abort. They can fail if the chosen read
- # timestamp is garbage collected; however, the default garbage
- # collection policy is generous enough that most applications do not
- # need to worry about this in practice.
- #
- # Snapshot read-only transactions do not need to call
- # Commit or
- # Rollback (and in fact are not
- # permitted to do so).
- #
- # To execute a snapshot transaction, the client specifies a timestamp
- # bound, which tells Cloud Spanner how to choose a read timestamp.
- #
- # The types of timestamp bound are:
- #
- # - Strong (the default).
- # - Bounded staleness.
- # - Exact staleness.
- #
- # If the Cloud Spanner database to be read is geographically distributed,
- # stale read-only transactions can execute more quickly than strong
- # or read-write transaction, because they are able to execute far
- # from the leader replica.
- #
- # Each type of timestamp bound is discussed in detail below.
- #
- # ### Strong
- #
- # Strong reads are guaranteed to see the effects of all transactions
- # that have committed before the start of the read. Furthermore, all
- # rows yielded by a single read are consistent with each other -- if
- # any part of the read observes a transaction, all parts of the read
- # see the transaction.
- #
- # Strong reads are not repeatable: two consecutive strong read-only
- # transactions might return inconsistent results if there are
- # concurrent writes. If consistency across reads is required, the
- # reads should be executed within a transaction or at an exact read
- # timestamp.
- #
- # See TransactionOptions.ReadOnly.strong.
- #
- # ### Exact Staleness
- #
- # These timestamp bounds execute reads at a user-specified
- # timestamp. Reads at a timestamp are guaranteed to see a consistent
- # prefix of the global transaction history: they observe
- # modifications done by all transactions with a commit timestamp <=
- # the read timestamp, and observe none of the modifications done by
- # transactions with a larger commit timestamp. They will block until
- # all conflicting transactions that may be assigned commit timestamps
- # <= the read timestamp have finished.
- #
- # The timestamp can either be expressed as an absolute Cloud Spanner commit
- # timestamp or a staleness relative to the current time.
- #
- # These modes do not require a "negotiation phase" to pick a
- # timestamp. As a result, they execute slightly faster than the
- # equivalent boundedly stale concurrency modes. On the other hand,
- # boundedly stale reads usually return fresher results.
- #
- # See TransactionOptions.ReadOnly.read_timestamp and
- # TransactionOptions.ReadOnly.exact_staleness.
- #
- # ### Bounded Staleness
- #
- # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
- # subject to a user-provided staleness bound. Cloud Spanner chooses the
- # newest timestamp within the staleness bound that allows execution
- # of the reads at the closest available replica without blocking.
- #
- # All rows yielded are consistent with each other -- if any part of
- # the read observes a transaction, all parts of the read see the
- # transaction. Boundedly stale reads are not repeatable: two stale
- # reads, even if they use the same staleness bound, can execute at
- # different timestamps and thus return inconsistent results.
- #
- # Boundedly stale reads execute in two phases: the first phase
- # negotiates a timestamp among all replicas needed to serve the
- # read. In the second phase, reads are executed at the negotiated
- # timestamp.
- #
- # As a result of the two phase execution, bounded staleness reads are
- # usually a little slower than comparable exact staleness
- # reads. However, they are typically able to return fresher
- # results, and are more likely to execute at the closest replica.
- #
- # Because the timestamp negotiation requires up-front knowledge of
- # which rows will be read, it can only be used with single-use
- # read-only transactions.
- #
- # See TransactionOptions.ReadOnly.max_staleness and
- # TransactionOptions.ReadOnly.min_read_timestamp.
- #
- # ### Old Read Timestamps and Garbage Collection
- #
- # Cloud Spanner continuously garbage collects deleted and overwritten data
- # in the background to reclaim storage space. This process is known
- # as "version GC". By default, version GC reclaims versions after they
- # are one hour old. Because of this, Cloud Spanner cannot perform reads
- # at read timestamps more than one hour in the past. This
- # restriction also applies to in-progress reads and/or SQL queries whose
- # timestamp become too old while executing. Reads and SQL queries with
- # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
- #
- # ## Partitioned DML Transactions
- #
- # Partitioned DML transactions are used to execute DML statements with a
- # different execution strategy that provides different, and often better,
- # scalability properties for large, table-wide operations than DML in a
- # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
- # should prefer using ReadWrite transactions.
- #
- # Partitioned DML partitions the keyspace and runs the DML statement on each
- # partition in separate, internal transactions. These transactions commit
- # automatically when complete, and run independently from one another.
- #
- # To reduce lock contention, this execution strategy only acquires read locks
- # on rows that match the WHERE clause of the statement. Additionally, the
- # smaller per-partition transactions hold locks for less time.
- #
- # That said, Partitioned DML is not a drop-in replacement for standard DML used
- # in ReadWrite transactions.
- #
- # - The DML statement must be fully-partitionable. Specifically, the statement
- # must be expressible as the union of many statements which each access only
- # a single row of the table.
- #
- # - The statement is not applied atomically to all rows of the table. Rather,
- # the statement is applied atomically to partitions of the table, in
- # independent transactions. Secondary index rows are updated atomically
- # with the base table rows.
- #
- # - Partitioned DML does not guarantee exactly-once execution semantics
- # against a partition. The statement will be applied at least once to each
- # partition. It is strongly recommended that the DML statement should be
- # idempotent to avoid unexpected results. For instance, it is potentially
- # dangerous to run a statement such as
- # `UPDATE table SET column = column + 1` as it could be run multiple times
- # against some rows.
- #
- # - The partitions are committed automatically - there is no support for
- # Commit or Rollback. If the call returns an error, or if the client issuing
- # the ExecuteSql call dies, it is possible that some rows had the statement
- # executed on them successfully. It is also possible that statement was
- # never executed against other rows.
- #
- # - Partitioned DML transactions may only contain the execution of a single
- # DML statement via ExecuteSql or ExecuteStreamingSql.
- #
- # - If any error is encountered during the execution of the partitioned DML
- # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
- # value that cannot be stored due to schema constraints), then the
- # operation is stopped at that point and an error is returned. It is
- # possible that at this point, some partitions have been committed (or even
- # committed multiple times), and other partitions have not been run at all.
- #
- # Given the above, Partitioned DML is good fit for large, database-wide,
- # operations that are idempotent, such as deleting old rows from a very large
- # table.
- "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
- #
- # Authorization to begin a Partitioned DML transaction requires
- # `spanner.databases.beginPartitionedDmlTransaction` permission
- # on the `session` resource.
- },
- "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
- #
- # Authorization to begin a read-only transaction requires
- # `spanner.databases.beginReadOnlyTransaction` permission
- # on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
- # seconds. Guarantees that all writes that have committed more
- # than the specified number of seconds ago are visible. Because
- # Cloud Spanner chooses the exact timestamp, this mode works even if
- # the client's local clock is substantially skewed from Cloud Spanner
- # commit timestamps.
- #
- # Useful for reading the freshest data available at a nearby
- # replica, while bounding the possible staleness if the local
- # replica has fallen behind.
- #
- # Note that this option can only be used in single-use
- # transactions.
- "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
- # the Transaction message that describes the transaction.
- "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
- # old. The timestamp is chosen soon after the read is started.
- #
- # Guarantees that all writes that have committed more than the
- # specified number of seconds ago are visible. Because Cloud Spanner
- # chooses the exact timestamp, this mode works even if the client's
- # local clock is substantially skewed from Cloud Spanner commit
- # timestamps.
- #
- # Useful for reading at nearby replicas without the distributed
- # timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
- },
- "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
- #
- # Authorization to begin a read-write transaction requires
- # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
- # on the `session` resource.
- # transaction type has no options.
- },
- },
+ "id": "A String", # Execute the read or SQL query in a previously-started transaction.
"begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in
# it. The transaction ID of the new transaction is returned in
# ResultSetMetadata.transaction, which is a Transaction.
@@ -2997,33 +2656,18 @@
# `spanner.databases.beginPartitionedDmlTransaction` permission
# on the `session` resource.
},
+ "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
+ #
+ # Authorization to begin a read-write transaction requires
+ # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
+ # on the `session` resource.
+ # transaction type has no options.
+ },
"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
#
# Authorization to begin a read-only transaction requires
# `spanner.databases.beginReadOnlyTransaction` permission
# on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
# seconds. Guarantees that all writes that have committed more
# than the specified number of seconds ago are visible. Because
@@ -3037,6 +2681,18 @@
#
# Note that this option can only be used in single-use
# transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
# the Transaction message that describes the transaction.
"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
@@ -3050,8 +2706,304 @@
#
# Useful for reading at nearby replicas without the distributed
# timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
+ },
+ "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
+ # This is the most efficient way to execute a transaction that
+ # consists of a single SQL query.
+ #
+ #
+ # Each session can have at most one active transaction at a time. After the
+ # active transaction is completed, the session can immediately be
+ # re-used for the next transaction. It is not necessary to create a
+ # new session for each transaction.
+ #
+ # # Transaction Modes
+ #
+ # Cloud Spanner supports three transaction modes:
+ #
+ # 1. Locking read-write. This type of transaction is the only way
+ # to write data into Cloud Spanner. These transactions rely on
+ # pessimistic locking and, if necessary, two-phase commit.
+ # Locking read-write transactions may abort, requiring the
+ # application to retry.
+ #
+ # 2. Snapshot read-only. 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. Snapshot read-only
+ # transactions do not need to be committed.
+ #
+ # 3. Partitioned DML. This type of transaction is used to execute
+ # a single Partitioned DML statement. Partitioned DML partitions
+ # the key space and runs the DML statement over each partition
+ # in parallel using separate, internal transactions that commit
+ # independently. Partitioned DML transactions do not need to be
+ # committed.
+ #
+ # For transactions that only read, snapshot read-only transactions
+ # provide simpler semantics and are almost always faster. In
+ # particular, read-only transactions do not take locks, so they do
+ # not conflict with read-write transactions. As a consequence of not
+ # taking locks, they also do not abort, so retry loops are not needed.
+ #
+ # Transactions may only read/write data in a single database. They
+ # may, however, read/write data in different tables within that
+ # database.
+ #
+ # ## Locking Read-Write Transactions
+ #
+ # Locking transactions may be used to atomically read-modify-write
+ # data anywhere in a database. This type of transaction is externally
+ # consistent.
+ #
+ # Clients should attempt to minimize the amount of time a transaction
+ # is active. Faster transactions commit with higher probability
+ # and cause less contention. Cloud Spanner attempts to keep read locks
+ # active as long as the transaction continues to do reads, and the
+ # transaction has not been terminated by
+ # Commit or
+ # Rollback. Long periods of
+ # inactivity at the client may cause Cloud Spanner to release a
+ # transaction's locks and abort it.
+ #
+ # Conceptually, a read-write transaction consists of zero or more
+ # reads or SQL statements followed by
+ # Commit. At any time before
+ # Commit, the client can send a
+ # Rollback request to abort the
+ # transaction.
+ #
+ # ### Semantics
+ #
+ # Cloud Spanner can commit the transaction if all read locks it acquired
+ # are still valid at commit time, and it is able to acquire write
+ # locks for all writes. Cloud Spanner can abort the transaction for any
+ # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
+ # that the transaction has not modified any user data in Cloud Spanner.
+ #
+ # Unless the transaction commits, Cloud Spanner makes no guarantees about
+ # how long the transaction's locks were held for. It is an error to
+ # use Cloud Spanner locks for any sort of mutual exclusion other than
+ # between Cloud Spanner transactions themselves.
+ #
+ # ### Retrying Aborted Transactions
+ #
+ # When a transaction aborts, the application can choose to retry the
+ # whole transaction again. To maximize the chances of successfully
+ # committing the retry, the client should execute the retry in the
+ # same session as the original attempt. The original session's lock
+ # priority increases with each consecutive abort, meaning that each
+ # attempt has a slightly better chance of success than the previous.
+ #
+ # Under some circumstances (e.g., many transactions attempting to
+ # modify the same row(s)), a transaction can abort many times in a
+ # short period before successfully committing. Thus, it is not a good
+ # idea to cap the number of retries a transaction can attempt;
+ # instead, it is better to limit the total amount of wall time spent
+ # retrying.
+ #
+ # ### Idle Transactions
+ #
+ # A transaction is considered idle if it has no outstanding reads or
+ # SQL queries and has not started a read or SQL query within the last 10
+ # seconds. Idle transactions can be aborted by Cloud Spanner so that they
+ # don't hold on to locks indefinitely. In that case, the commit will
+ # fail with error `ABORTED`.
+ #
+ # If this behavior is undesirable, periodically executing a simple
+ # SQL query in the transaction (e.g., `SELECT 1`) prevents the
+ # transaction from becoming idle.
+ #
+ # ## Snapshot Read-Only Transactions
+ #
+ # Snapshot read-only transactions provides a simpler method than
+ # locking read-write transactions for doing several consistent
+ # reads. However, this type of transaction does not support writes.
+ #
+ # Snapshot transactions do not take locks. Instead, they work by
+ # choosing a Cloud Spanner timestamp, then executing all reads at that
+ # timestamp. Since they do not acquire locks, they do not block
+ # concurrent read-write transactions.
+ #
+ # Unlike locking read-write transactions, snapshot read-only
+ # transactions never abort. They can fail if the chosen read
+ # timestamp is garbage collected; however, the default garbage
+ # collection policy is generous enough that most applications do not
+ # need to worry about this in practice.
+ #
+ # Snapshot read-only transactions do not need to call
+ # Commit or
+ # Rollback (and in fact are not
+ # permitted to do so).
+ #
+ # To execute a snapshot transaction, the client specifies a timestamp
+ # bound, which tells Cloud Spanner how to choose a read timestamp.
+ #
+ # The types of timestamp bound are:
+ #
+ # - Strong (the default).
+ # - Bounded staleness.
+ # - Exact staleness.
+ #
+ # If the Cloud Spanner database to be read is geographically distributed,
+ # stale read-only transactions can execute more quickly than strong
+ # or read-write transaction, because they are able to execute far
+ # from the leader replica.
+ #
+ # Each type of timestamp bound is discussed in detail below.
+ #
+ # ### Strong
+ #
+ # Strong reads are guaranteed to see the effects of all transactions
+ # that have committed before the start of the read. Furthermore, all
+ # rows yielded by a single read are consistent with each other -- if
+ # any part of the read observes a transaction, all parts of the read
+ # see the transaction.
+ #
+ # Strong reads are not repeatable: two consecutive strong read-only
+ # transactions might return inconsistent results if there are
+ # concurrent writes. If consistency across reads is required, the
+ # reads should be executed within a transaction or at an exact read
+ # timestamp.
+ #
+ # See TransactionOptions.ReadOnly.strong.
+ #
+ # ### Exact Staleness
+ #
+ # These timestamp bounds execute reads at a user-specified
+ # timestamp. Reads at a timestamp are guaranteed to see a consistent
+ # prefix of the global transaction history: they observe
+ # modifications done by all transactions with a commit timestamp <=
+ # the read timestamp, and observe none of the modifications done by
+ # transactions with a larger commit timestamp. They will block until
+ # all conflicting transactions that may be assigned commit timestamps
+ # <= the read timestamp have finished.
+ #
+ # The timestamp can either be expressed as an absolute Cloud Spanner commit
+ # timestamp or a staleness relative to the current time.
+ #
+ # These modes do not require a "negotiation phase" to pick a
+ # timestamp. As a result, they execute slightly faster than the
+ # equivalent boundedly stale concurrency modes. On the other hand,
+ # boundedly stale reads usually return fresher results.
+ #
+ # See TransactionOptions.ReadOnly.read_timestamp and
+ # TransactionOptions.ReadOnly.exact_staleness.
+ #
+ # ### Bounded Staleness
+ #
+ # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
+ # subject to a user-provided staleness bound. Cloud Spanner chooses the
+ # newest timestamp within the staleness bound that allows execution
+ # of the reads at the closest available replica without blocking.
+ #
+ # All rows yielded are consistent with each other -- if any part of
+ # the read observes a transaction, all parts of the read see the
+ # transaction. Boundedly stale reads are not repeatable: two stale
+ # reads, even if they use the same staleness bound, can execute at
+ # different timestamps and thus return inconsistent results.
+ #
+ # Boundedly stale reads execute in two phases: the first phase
+ # negotiates a timestamp among all replicas needed to serve the
+ # read. In the second phase, reads are executed at the negotiated
+ # timestamp.
+ #
+ # As a result of the two phase execution, bounded staleness reads are
+ # usually a little slower than comparable exact staleness
+ # reads. However, they are typically able to return fresher
+ # results, and are more likely to execute at the closest replica.
+ #
+ # Because the timestamp negotiation requires up-front knowledge of
+ # which rows will be read, it can only be used with single-use
+ # read-only transactions.
+ #
+ # See TransactionOptions.ReadOnly.max_staleness and
+ # TransactionOptions.ReadOnly.min_read_timestamp.
+ #
+ # ### Old Read Timestamps and Garbage Collection
+ #
+ # Cloud Spanner continuously garbage collects deleted and overwritten data
+ # in the background to reclaim storage space. This process is known
+ # as "version GC". By default, version GC reclaims versions after they
+ # are one hour old. Because of this, Cloud Spanner cannot perform reads
+ # at read timestamps more than one hour in the past. This
+ # restriction also applies to in-progress reads and/or SQL queries whose
+ # timestamp become too old while executing. Reads and SQL queries with
+ # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
+ #
+ # ## Partitioned DML Transactions
+ #
+ # Partitioned DML transactions are used to execute DML statements with a
+ # different execution strategy that provides different, and often better,
+ # scalability properties for large, table-wide operations than DML in a
+ # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+ # should prefer using ReadWrite transactions.
+ #
+ # Partitioned DML partitions the keyspace and runs the DML statement on each
+ # partition in separate, internal transactions. These transactions commit
+ # automatically when complete, and run independently from one another.
+ #
+ # To reduce lock contention, this execution strategy only acquires read locks
+ # on rows that match the WHERE clause of the statement. Additionally, the
+ # smaller per-partition transactions hold locks for less time.
+ #
+ # That said, Partitioned DML is not a drop-in replacement for standard DML used
+ # in ReadWrite transactions.
+ #
+ # - The DML statement must be fully-partitionable. Specifically, the statement
+ # must be expressible as the union of many statements which each access only
+ # a single row of the table.
+ #
+ # - The statement is not applied atomically to all rows of the table. Rather,
+ # the statement is applied atomically to partitions of the table, in
+ # independent transactions. Secondary index rows are updated atomically
+ # with the base table rows.
+ #
+ # - Partitioned DML does not guarantee exactly-once execution semantics
+ # against a partition. The statement will be applied at least once to each
+ # partition. It is strongly recommended that the DML statement should be
+ # idempotent to avoid unexpected results. For instance, it is potentially
+ # dangerous to run a statement such as
+ # `UPDATE table SET column = column + 1` as it could be run multiple times
+ # against some rows.
+ #
+ # - The partitions are committed automatically - there is no support for
+ # Commit or Rollback. If the call returns an error, or if the client issuing
+ # the ExecuteSql call dies, it is possible that some rows had the statement
+ # executed on them successfully. It is also possible that statement was
+ # never executed against other rows.
+ #
+ # - Partitioned DML transactions may only contain the execution of a single
+ # DML statement via ExecuteSql or ExecuteStreamingSql.
+ #
+ # - If any error is encountered during the execution of the partitioned DML
+ # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
+ # value that cannot be stored due to schema constraints), then the
+ # operation is stopped at that point and an error is returned. It is
+ # possible that at this point, some partitions have been committed (or even
+ # committed multiple times), and other partitions have not been run at all.
+ #
+ # Given the above, Partitioned DML is good fit for large, database-wide,
+ # operations that are idempotent, such as deleting old rows from a very large
+ # table.
+ "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
+ #
+ # Authorization to begin a Partitioned DML transaction requires
+ # `spanner.databases.beginPartitionedDmlTransaction` permission
+ # on the `session` resource.
},
"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
#
@@ -3060,29 +3012,113 @@
# on the `session` resource.
# transaction type has no options.
},
+ "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
+ #
+ # Authorization to begin a read-only transaction requires
+ # `spanner.databases.beginReadOnlyTransaction` permission
+ # on the `session` resource.
+ "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
+ # seconds. Guarantees that all writes that have committed more
+ # than the specified number of seconds ago are visible. Because
+ # Cloud Spanner chooses the exact timestamp, this mode works even if
+ # the client's local clock is substantially skewed from Cloud Spanner
+ # commit timestamps.
+ #
+ # Useful for reading the freshest data available at a nearby
+ # replica, while bounding the possible staleness if the local
+ # replica has fallen behind.
+ #
+ # Note that this option can only be used in single-use
+ # transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
+ "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
+ # the Transaction message that describes the transaction.
+ "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
+ # old. The timestamp is chosen soon after the read is started.
+ #
+ # Guarantees that all writes that have committed more than the
+ # specified number of seconds ago are visible. Because Cloud Spanner
+ # chooses the exact timestamp, this mode works even if the client's
+ # local clock is substantially skewed from Cloud Spanner commit
+ # timestamps.
+ #
+ # Useful for reading at nearby replicas without the distributed
+ # timestamp negotiation overhead of `max_staleness`.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
},
- "id": "A String", # Execute the read or SQL query in a previously-started transaction.
},
+ "queryMode": "A String", # Used to control the amount of debugging information returned in
+ # ResultSetStats. If partition_token is set, query_mode can only
+ # be set to QueryMode.NORMAL.
+ "partitionToken": "A String", # If present, results will be restricted to the specified partition
+ # previously created using PartitionQuery(). There must be an exact
+ # match for the values of fields common to this message and the
+ # PartitionQueryRequest message used to create this partition_token.
"resumeToken": "A String", # If this request is resuming a previously interrupted SQL statement
# execution, `resume_token` should be copied from the last
# PartialResultSet yielded before the interruption. Doing this
# enables the new SQL statement execution to resume where the last one left
# off. The rest of the request parameters must exactly match the
# request that yielded this token.
- "partitionToken": "A String", # If present, results will be restricted to the specified partition
- # previously created using PartitionQuery(). There must be an exact
- # match for the values of fields common to this message and the
- # PartitionQueryRequest message used to create this partition_token.
- "seqno": "A String", # A per-transaction sequence number used to identify this request. This field
- # makes each request idempotent such that if the request is received multiple
- # times, at most one will succeed.
+ "queryOptions": { # Query optimizer configuration. # Query optimizer configuration to use for the given query.
+ "optimizerVersion": "A String", # An option to control the selection of optimizer version.
+ #
+ # This parameter allows individual queries to pick different query
+ # optimizer versions.
+ #
+ # Specifying "latest" as a value instructs Cloud Spanner to use the
+ # latest supported query optimizer version. If not specified, Cloud Spanner
+ # uses optimizer version set at the database level options. Any other
+ # positive integer (from the list of supported optimizer versions)
+ # overrides the default optimizer version for query execution.
+ # The list of supported optimizer versions can be queried from
+ # SPANNER_SYS.SUPPORTED_OPTIMIZER_VERSIONS. Executing a SQL statement
+ # with an invalid optimizer version will fail with a syntax error
+ # (`INVALID_ARGUMENT`) status.
+ # See
+ # https://cloud.google.com/spanner/docs/query-optimizer/manage-query-optimizer
+ # for more information on managing the query optimizer.
+ #
+ # The `optimizer_version` statement hint has precedence over this setting.
+ },
+ "params": { # Parameter names and values that bind to placeholders in the SQL string.
#
- # The sequence number must be monotonically increasing within the
- # transaction. If a request arrives for the first time with an out-of-order
- # sequence number, the transaction may be aborted. Replays of previously
- # handled requests will yield the same response as the first execution.
+ # A parameter placeholder consists of the `@` character followed by the
+ # parameter name (for example, `@firstName`). Parameter names can contain
+ # letters, numbers, and underscores.
#
- # Required for DML statements. Ignored for queries.
+ # Parameters can appear anywhere that a literal value is expected. The same
+ # parameter name can be used more than once, for example:
+ #
+ # `"WHERE id > @msg_id AND id < @msg_id + 100"`
+ #
+ # It is an error to execute a SQL statement with unbound parameters.
+ "a_key": "", # Properties of the object.
+ },
+ "sql": "A String", # Required. The SQL string.
"paramTypes": { # It is not always possible for Cloud Spanner to infer the right SQL type
# from a JSON value. For example, values of type `BYTES` and values
# of type `STRING` both appear in params as JSON strings.
@@ -3118,39 +3154,6 @@
},
},
},
- "sql": "A String", # Required. The SQL string.
- "params": { # Parameter names and values that bind to placeholders in the SQL string.
- #
- # A parameter placeholder consists of the `@` character followed by the
- # parameter name (for example, `@firstName`). Parameter names can contain
- # letters, numbers, and underscores.
- #
- # Parameters can appear anywhere that a literal value is expected. The same
- # parameter name can be used more than once, for example:
- #
- # `"WHERE id > @msg_id AND id < @msg_id + 100"`
- #
- # It is an error to execute a SQL statement with unbound parameters.
- "a_key": "", # Properties of the object.
- },
- "queryOptions": { # Query optimizer configuration. # Query optimizer configuration to use for the given query.
- "optimizerVersion": "A String", # An option to control the selection of optimizer version.
- #
- # This parameter allows individual queries to pick different query
- # optimizer versions.
- #
- # Specifying "latest" as a value instructs Cloud Spanner to use the
- # latest supported query optimizer version. If not specified, Cloud Spanner
- # uses optimizer version set at the database level options. Any other
- # positive integer (from the list of supported optimizer versions)
- # overrides the default optimizer version for query execution.
- # The list of supported optimizer versions can be queried from
- # SPANNER_SYS.SUPPORTED_OPTIMIZER_VERSIONS. Executing a SQL statement
- # with an invalid optimizer version will fail with a syntax error
- # (`INVALID_ARGUMENT`) status.
- #
- # The `optimizer_version` statement hint has precedence over this setting.
- },
}
x__xgafv: string, V1 error format.
@@ -3163,99 +3166,6 @@
{ # Results from Read or
# ExecuteSql.
- "stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the SQL statement that
- # produced this result set. These can be requested by setting
- # ExecuteSqlRequest.query_mode.
- # DML statements always produce stats containing the number of rows
- # modified, unless executed using the
- # ExecuteSqlRequest.QueryMode.PLAN ExecuteSqlRequest.query_mode.
- # Other fields may or may not be populated, based on the
- # ExecuteSqlRequest.query_mode.
- "rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.
- "queryStats": { # Aggregated statistics from the execution of the query. Only present when
- # the query is profiled. For example, a query could return the statistics as
- # follows:
- #
- # {
- # "rows_returned": "3",
- # "elapsed_time": "1.22 secs",
- # "cpu_time": "1.19 secs"
- # }
- "a_key": "", # Properties of the object.
- },
- "rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it
- # returns a lower bound of the rows modified.
- "queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
- "planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
- # with the plan root. Each PlanNode's `id` corresponds to its index in
- # `plan_nodes`.
- { # Node information for nodes appearing in a QueryPlan.plan_nodes.
- "metadata": { # Attributes relevant to the node contained in a group of key-value pairs.
- # For example, a Parameter Reference node could have the following
- # information in its metadata:
- #
- # {
- # "parameter_reference": "param1",
- # "parameter_type": "array"
- # }
- "a_key": "", # Properties of the object.
- },
- "executionStats": { # The execution statistics associated with the node, contained in a group of
- # key-value pairs. Only present if the plan was returned as a result of a
- # profile query. For example, number of executions, number of rows/time per
- # execution etc.
- "a_key": "", # Properties of the object.
- },
- "shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
- # `SCALAR` PlanNode(s).
- "description": "A String", # A string representation of the expression subtree rooted at this node.
- "subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases
- # where the `description` string of this node references a `SCALAR`
- # subquery contained in the expression subtree rooted at this node. The
- # referenced `SCALAR` subquery may not necessarily be a direct child of
- # this node.
- "a_key": 42,
- },
- },
- "index": 42, # The `PlanNode`'s index in node list.
- "kind": "A String", # Used to determine the type of node. May be needed for visualizing
- # different kinds of nodes differently. For example, If the node is a
- # SCALAR node, it will have a condensed representation
- # which can be used to directly embed a description of the node in its
- # parent.
- "displayName": "A String", # The display name for the node.
- "childLinks": [ # List of child node `index`es and their relationship to this parent.
- { # Metadata associated with a parent-child relationship appearing in a
- # PlanNode.
- "variable": "A String", # Only present if the child node is SCALAR and corresponds
- # to an output variable of the parent node. The field carries the name of
- # the output variable.
- # For example, a `TableScan` operator that reads rows from a table will
- # have child links to the `SCALAR` nodes representing the output variables
- # created for each column that is read by the operator. The corresponding
- # `variable` fields will be set to the variable names assigned to the
- # columns.
- "childIndex": 42, # The node to which the link points.
- "type": "A String", # The type of the link. For example, in Hash Joins this could be used to
- # distinguish between the build child and the probe child, or in the case
- # of the child being an output variable, to represent the tag associated
- # with the output variable.
- },
- ],
- },
- ],
- },
- },
- "rows": [ # Each element in `rows` is a row whose format is defined by
- # metadata.row_type. The ith element
- # in each row matches the ith field in
- # metadata.row_type. Elements are
- # encoded based on type as described
- # here.
- [
- "",
- ],
- ],
"metadata": { # Metadata about a ResultSet or PartialResultSet. # Metadata about the result set, such as row type information.
"rowType": { # `StructType` defines the fields of a STRUCT type. # Indicates the field names and types for the rows in the result
# set. For example, a SQL query like `"SELECT UserId, UserName FROM
@@ -3285,6 +3195,12 @@
},
"transaction": { # A transaction. # If the read or SQL query began a transaction as a side-effect, the
# information about the new transaction is yielded here.
+ "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
+ # for the transaction. Not returned by default: see
+ # TransactionOptions.ReadOnly.return_read_timestamp.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
"id": "A String", # `id` may be used to identify the transaction in subsequent
# Read,
# ExecuteSql,
@@ -3293,14 +3209,101 @@
#
# Single-use read-only transactions do not have IDs, because
# single-use transactions do not support multiple requests.
- "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
- # for the transaction. Not returned by default: see
- # TransactionOptions.ReadOnly.return_read_timestamp.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
},
},
+ "stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the SQL statement that
+ # produced this result set. These can be requested by setting
+ # ExecuteSqlRequest.query_mode.
+ # DML statements always produce stats containing the number of rows
+ # modified, unless executed using the
+ # ExecuteSqlRequest.QueryMode.PLAN ExecuteSqlRequest.query_mode.
+ # Other fields may or may not be populated, based on the
+ # ExecuteSqlRequest.query_mode.
+ "rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it
+ # returns a lower bound of the rows modified.
+ "queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
+ "planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
+ # with the plan root. Each PlanNode's `id` corresponds to its index in
+ # `plan_nodes`.
+ { # Node information for nodes appearing in a QueryPlan.plan_nodes.
+ "displayName": "A String", # The display name for the node.
+ "executionStats": { # The execution statistics associated with the node, contained in a group of
+ # key-value pairs. Only present if the plan was returned as a result of a
+ # profile query. For example, number of executions, number of rows/time per
+ # execution etc.
+ "a_key": "", # Properties of the object.
+ },
+ "shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
+ # `SCALAR` PlanNode(s).
+ "subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases
+ # where the `description` string of this node references a `SCALAR`
+ # subquery contained in the expression subtree rooted at this node. The
+ # referenced `SCALAR` subquery may not necessarily be a direct child of
+ # this node.
+ "a_key": 42,
+ },
+ "description": "A String", # A string representation of the expression subtree rooted at this node.
+ },
+ "metadata": { # Attributes relevant to the node contained in a group of key-value pairs.
+ # For example, a Parameter Reference node could have the following
+ # information in its metadata:
+ #
+ # {
+ # "parameter_reference": "param1",
+ # "parameter_type": "array"
+ # }
+ "a_key": "", # Properties of the object.
+ },
+ "childLinks": [ # List of child node `index`es and their relationship to this parent.
+ { # Metadata associated with a parent-child relationship appearing in a
+ # PlanNode.
+ "type": "A String", # The type of the link. For example, in Hash Joins this could be used to
+ # distinguish between the build child and the probe child, or in the case
+ # of the child being an output variable, to represent the tag associated
+ # with the output variable.
+ "variable": "A String", # Only present if the child node is SCALAR and corresponds
+ # to an output variable of the parent node. The field carries the name of
+ # the output variable.
+ # For example, a `TableScan` operator that reads rows from a table will
+ # have child links to the `SCALAR` nodes representing the output variables
+ # created for each column that is read by the operator. The corresponding
+ # `variable` fields will be set to the variable names assigned to the
+ # columns.
+ "childIndex": 42, # The node to which the link points.
+ },
+ ],
+ "index": 42, # The `PlanNode`'s index in node list.
+ "kind": "A String", # Used to determine the type of node. May be needed for visualizing
+ # different kinds of nodes differently. For example, If the node is a
+ # SCALAR node, it will have a condensed representation
+ # which can be used to directly embed a description of the node in its
+ # parent.
+ },
+ ],
+ },
+ "rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.
+ "queryStats": { # Aggregated statistics from the execution of the query. Only present when
+ # the query is profiled. For example, a query could return the statistics as
+ # follows:
+ #
+ # {
+ # "rows_returned": "3",
+ # "elapsed_time": "1.22 secs",
+ # "cpu_time": "1.19 secs"
+ # }
+ "a_key": "", # Properties of the object.
+ },
+ },
+ "rows": [ # Each element in `rows` is a row whose format is defined by
+ # metadata.row_type. The ith element
+ # in each row matches the ith field in
+ # metadata.row_type. Elements are
+ # encoded based on type as described
+ # here.
+ [
+ "",
+ ],
+ ],
}</pre>
</div>
@@ -3319,9 +3322,16 @@
{ # The request for ExecuteSql and
# ExecuteStreamingSql.
- "queryMode": "A String", # Used to control the amount of debugging information returned in
- # ResultSetStats. If partition_token is set, query_mode can only
- # be set to QueryMode.NORMAL.
+ "seqno": "A String", # A per-transaction sequence number used to identify this request. This field
+ # makes each request idempotent such that if the request is received multiple
+ # times, at most one will succeed.
+ #
+ # The sequence number must be monotonically increasing within the
+ # transaction. If a request arrives for the first time with an out-of-order
+ # sequence number, the transaction may be aborted. Replays of previously
+ # handled requests will yield the same response as the first execution.
+ #
+ # Required for DML statements. Ignored for queries.
"transaction": { # This message is used to select the transaction in which a # The transaction to use.
#
# For queries, if none is provided, the default is a temporary read-only
@@ -3336,355 +3346,7 @@
# ExecuteSql call runs.
#
# See TransactionOptions for more information about transactions.
- "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
- # This is the most efficient way to execute a transaction that
- # consists of a single SQL query.
- #
- #
- # Each session can have at most one active transaction at a time. After the
- # active transaction is completed, the session can immediately be
- # re-used for the next transaction. It is not necessary to create a
- # new session for each transaction.
- #
- # # Transaction Modes
- #
- # Cloud Spanner supports three transaction modes:
- #
- # 1. Locking read-write. This type of transaction is the only way
- # to write data into Cloud Spanner. These transactions rely on
- # pessimistic locking and, if necessary, two-phase commit.
- # Locking read-write transactions may abort, requiring the
- # application to retry.
- #
- # 2. Snapshot read-only. 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. Snapshot read-only
- # transactions do not need to be committed.
- #
- # 3. Partitioned DML. This type of transaction is used to execute
- # a single Partitioned DML statement. Partitioned DML partitions
- # the key space and runs the DML statement over each partition
- # in parallel using separate, internal transactions that commit
- # independently. Partitioned DML transactions do not need to be
- # committed.
- #
- # For transactions that only read, snapshot read-only transactions
- # provide simpler semantics and are almost always faster. In
- # particular, read-only transactions do not take locks, so they do
- # not conflict with read-write transactions. As a consequence of not
- # taking locks, they also do not abort, so retry loops are not needed.
- #
- # Transactions may only read/write data in a single database. They
- # may, however, read/write data in different tables within that
- # database.
- #
- # ## Locking Read-Write Transactions
- #
- # Locking transactions may be used to atomically read-modify-write
- # data anywhere in a database. This type of transaction is externally
- # consistent.
- #
- # Clients should attempt to minimize the amount of time a transaction
- # is active. Faster transactions commit with higher probability
- # and cause less contention. Cloud Spanner attempts to keep read locks
- # active as long as the transaction continues to do reads, and the
- # transaction has not been terminated by
- # Commit or
- # Rollback. Long periods of
- # inactivity at the client may cause Cloud Spanner to release a
- # transaction's locks and abort it.
- #
- # Conceptually, a read-write transaction consists of zero or more
- # reads or SQL statements followed by
- # Commit. At any time before
- # Commit, the client can send a
- # Rollback request to abort the
- # transaction.
- #
- # ### Semantics
- #
- # Cloud Spanner can commit the transaction if all read locks it acquired
- # are still valid at commit time, and it is able to acquire write
- # locks for all writes. Cloud Spanner can abort the transaction for any
- # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
- # that the transaction has not modified any user data in Cloud Spanner.
- #
- # Unless the transaction commits, Cloud Spanner makes no guarantees about
- # how long the transaction's locks were held for. It is an error to
- # use Cloud Spanner locks for any sort of mutual exclusion other than
- # between Cloud Spanner transactions themselves.
- #
- # ### Retrying Aborted Transactions
- #
- # When a transaction aborts, the application can choose to retry the
- # whole transaction again. To maximize the chances of successfully
- # committing the retry, the client should execute the retry in the
- # same session as the original attempt. The original session's lock
- # priority increases with each consecutive abort, meaning that each
- # attempt has a slightly better chance of success than the previous.
- #
- # Under some circumstances (e.g., many transactions attempting to
- # modify the same row(s)), a transaction can abort many times in a
- # short period before successfully committing. Thus, it is not a good
- # idea to cap the number of retries a transaction can attempt;
- # instead, it is better to limit the total amount of wall time spent
- # retrying.
- #
- # ### Idle Transactions
- #
- # A transaction is considered idle if it has no outstanding reads or
- # SQL queries and has not started a read or SQL query within the last 10
- # seconds. Idle transactions can be aborted by Cloud Spanner so that they
- # don't hold on to locks indefinitely. In that case, the commit will
- # fail with error `ABORTED`.
- #
- # If this behavior is undesirable, periodically executing a simple
- # SQL query in the transaction (e.g., `SELECT 1`) prevents the
- # transaction from becoming idle.
- #
- # ## Snapshot Read-Only Transactions
- #
- # Snapshot read-only transactions provides a simpler method than
- # locking read-write transactions for doing several consistent
- # reads. However, this type of transaction does not support writes.
- #
- # Snapshot transactions do not take locks. Instead, they work by
- # choosing a Cloud Spanner timestamp, then executing all reads at that
- # timestamp. Since they do not acquire locks, they do not block
- # concurrent read-write transactions.
- #
- # Unlike locking read-write transactions, snapshot read-only
- # transactions never abort. They can fail if the chosen read
- # timestamp is garbage collected; however, the default garbage
- # collection policy is generous enough that most applications do not
- # need to worry about this in practice.
- #
- # Snapshot read-only transactions do not need to call
- # Commit or
- # Rollback (and in fact are not
- # permitted to do so).
- #
- # To execute a snapshot transaction, the client specifies a timestamp
- # bound, which tells Cloud Spanner how to choose a read timestamp.
- #
- # The types of timestamp bound are:
- #
- # - Strong (the default).
- # - Bounded staleness.
- # - Exact staleness.
- #
- # If the Cloud Spanner database to be read is geographically distributed,
- # stale read-only transactions can execute more quickly than strong
- # or read-write transaction, because they are able to execute far
- # from the leader replica.
- #
- # Each type of timestamp bound is discussed in detail below.
- #
- # ### Strong
- #
- # Strong reads are guaranteed to see the effects of all transactions
- # that have committed before the start of the read. Furthermore, all
- # rows yielded by a single read are consistent with each other -- if
- # any part of the read observes a transaction, all parts of the read
- # see the transaction.
- #
- # Strong reads are not repeatable: two consecutive strong read-only
- # transactions might return inconsistent results if there are
- # concurrent writes. If consistency across reads is required, the
- # reads should be executed within a transaction or at an exact read
- # timestamp.
- #
- # See TransactionOptions.ReadOnly.strong.
- #
- # ### Exact Staleness
- #
- # These timestamp bounds execute reads at a user-specified
- # timestamp. Reads at a timestamp are guaranteed to see a consistent
- # prefix of the global transaction history: they observe
- # modifications done by all transactions with a commit timestamp <=
- # the read timestamp, and observe none of the modifications done by
- # transactions with a larger commit timestamp. They will block until
- # all conflicting transactions that may be assigned commit timestamps
- # <= the read timestamp have finished.
- #
- # The timestamp can either be expressed as an absolute Cloud Spanner commit
- # timestamp or a staleness relative to the current time.
- #
- # These modes do not require a "negotiation phase" to pick a
- # timestamp. As a result, they execute slightly faster than the
- # equivalent boundedly stale concurrency modes. On the other hand,
- # boundedly stale reads usually return fresher results.
- #
- # See TransactionOptions.ReadOnly.read_timestamp and
- # TransactionOptions.ReadOnly.exact_staleness.
- #
- # ### Bounded Staleness
- #
- # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
- # subject to a user-provided staleness bound. Cloud Spanner chooses the
- # newest timestamp within the staleness bound that allows execution
- # of the reads at the closest available replica without blocking.
- #
- # All rows yielded are consistent with each other -- if any part of
- # the read observes a transaction, all parts of the read see the
- # transaction. Boundedly stale reads are not repeatable: two stale
- # reads, even if they use the same staleness bound, can execute at
- # different timestamps and thus return inconsistent results.
- #
- # Boundedly stale reads execute in two phases: the first phase
- # negotiates a timestamp among all replicas needed to serve the
- # read. In the second phase, reads are executed at the negotiated
- # timestamp.
- #
- # As a result of the two phase execution, bounded staleness reads are
- # usually a little slower than comparable exact staleness
- # reads. However, they are typically able to return fresher
- # results, and are more likely to execute at the closest replica.
- #
- # Because the timestamp negotiation requires up-front knowledge of
- # which rows will be read, it can only be used with single-use
- # read-only transactions.
- #
- # See TransactionOptions.ReadOnly.max_staleness and
- # TransactionOptions.ReadOnly.min_read_timestamp.
- #
- # ### Old Read Timestamps and Garbage Collection
- #
- # Cloud Spanner continuously garbage collects deleted and overwritten data
- # in the background to reclaim storage space. This process is known
- # as "version GC". By default, version GC reclaims versions after they
- # are one hour old. Because of this, Cloud Spanner cannot perform reads
- # at read timestamps more than one hour in the past. This
- # restriction also applies to in-progress reads and/or SQL queries whose
- # timestamp become too old while executing. Reads and SQL queries with
- # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
- #
- # ## Partitioned DML Transactions
- #
- # Partitioned DML transactions are used to execute DML statements with a
- # different execution strategy that provides different, and often better,
- # scalability properties for large, table-wide operations than DML in a
- # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
- # should prefer using ReadWrite transactions.
- #
- # Partitioned DML partitions the keyspace and runs the DML statement on each
- # partition in separate, internal transactions. These transactions commit
- # automatically when complete, and run independently from one another.
- #
- # To reduce lock contention, this execution strategy only acquires read locks
- # on rows that match the WHERE clause of the statement. Additionally, the
- # smaller per-partition transactions hold locks for less time.
- #
- # That said, Partitioned DML is not a drop-in replacement for standard DML used
- # in ReadWrite transactions.
- #
- # - The DML statement must be fully-partitionable. Specifically, the statement
- # must be expressible as the union of many statements which each access only
- # a single row of the table.
- #
- # - The statement is not applied atomically to all rows of the table. Rather,
- # the statement is applied atomically to partitions of the table, in
- # independent transactions. Secondary index rows are updated atomically
- # with the base table rows.
- #
- # - Partitioned DML does not guarantee exactly-once execution semantics
- # against a partition. The statement will be applied at least once to each
- # partition. It is strongly recommended that the DML statement should be
- # idempotent to avoid unexpected results. For instance, it is potentially
- # dangerous to run a statement such as
- # `UPDATE table SET column = column + 1` as it could be run multiple times
- # against some rows.
- #
- # - The partitions are committed automatically - there is no support for
- # Commit or Rollback. If the call returns an error, or if the client issuing
- # the ExecuteSql call dies, it is possible that some rows had the statement
- # executed on them successfully. It is also possible that statement was
- # never executed against other rows.
- #
- # - Partitioned DML transactions may only contain the execution of a single
- # DML statement via ExecuteSql or ExecuteStreamingSql.
- #
- # - If any error is encountered during the execution of the partitioned DML
- # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
- # value that cannot be stored due to schema constraints), then the
- # operation is stopped at that point and an error is returned. It is
- # possible that at this point, some partitions have been committed (or even
- # committed multiple times), and other partitions have not been run at all.
- #
- # Given the above, Partitioned DML is good fit for large, database-wide,
- # operations that are idempotent, such as deleting old rows from a very large
- # table.
- "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
- #
- # Authorization to begin a Partitioned DML transaction requires
- # `spanner.databases.beginPartitionedDmlTransaction` permission
- # on the `session` resource.
- },
- "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
- #
- # Authorization to begin a read-only transaction requires
- # `spanner.databases.beginReadOnlyTransaction` permission
- # on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
- # seconds. Guarantees that all writes that have committed more
- # than the specified number of seconds ago are visible. Because
- # Cloud Spanner chooses the exact timestamp, this mode works even if
- # the client's local clock is substantially skewed from Cloud Spanner
- # commit timestamps.
- #
- # Useful for reading the freshest data available at a nearby
- # replica, while bounding the possible staleness if the local
- # replica has fallen behind.
- #
- # Note that this option can only be used in single-use
- # transactions.
- "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
- # the Transaction message that describes the transaction.
- "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
- # old. The timestamp is chosen soon after the read is started.
- #
- # Guarantees that all writes that have committed more than the
- # specified number of seconds ago are visible. Because Cloud Spanner
- # chooses the exact timestamp, this mode works even if the client's
- # local clock is substantially skewed from Cloud Spanner commit
- # timestamps.
- #
- # Useful for reading at nearby replicas without the distributed
- # timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
- },
- "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
- #
- # Authorization to begin a read-write transaction requires
- # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
- # on the `session` resource.
- # transaction type has no options.
- },
- },
+ "id": "A String", # Execute the read or SQL query in a previously-started transaction.
"begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in
# it. The transaction ID of the new transaction is returned in
# ResultSetMetadata.transaction, which is a Transaction.
@@ -3970,33 +3632,18 @@
# `spanner.databases.beginPartitionedDmlTransaction` permission
# on the `session` resource.
},
+ "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
+ #
+ # Authorization to begin a read-write transaction requires
+ # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
+ # on the `session` resource.
+ # transaction type has no options.
+ },
"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
#
# Authorization to begin a read-only transaction requires
# `spanner.databases.beginReadOnlyTransaction` permission
# on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
# seconds. Guarantees that all writes that have committed more
# than the specified number of seconds ago are visible. Because
@@ -4010,6 +3657,18 @@
#
# Note that this option can only be used in single-use
# transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
# the Transaction message that describes the transaction.
"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
@@ -4023,8 +3682,304 @@
#
# Useful for reading at nearby replicas without the distributed
# timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
+ },
+ "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
+ # This is the most efficient way to execute a transaction that
+ # consists of a single SQL query.
+ #
+ #
+ # Each session can have at most one active transaction at a time. After the
+ # active transaction is completed, the session can immediately be
+ # re-used for the next transaction. It is not necessary to create a
+ # new session for each transaction.
+ #
+ # # Transaction Modes
+ #
+ # Cloud Spanner supports three transaction modes:
+ #
+ # 1. Locking read-write. This type of transaction is the only way
+ # to write data into Cloud Spanner. These transactions rely on
+ # pessimistic locking and, if necessary, two-phase commit.
+ # Locking read-write transactions may abort, requiring the
+ # application to retry.
+ #
+ # 2. Snapshot read-only. 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. Snapshot read-only
+ # transactions do not need to be committed.
+ #
+ # 3. Partitioned DML. This type of transaction is used to execute
+ # a single Partitioned DML statement. Partitioned DML partitions
+ # the key space and runs the DML statement over each partition
+ # in parallel using separate, internal transactions that commit
+ # independently. Partitioned DML transactions do not need to be
+ # committed.
+ #
+ # For transactions that only read, snapshot read-only transactions
+ # provide simpler semantics and are almost always faster. In
+ # particular, read-only transactions do not take locks, so they do
+ # not conflict with read-write transactions. As a consequence of not
+ # taking locks, they also do not abort, so retry loops are not needed.
+ #
+ # Transactions may only read/write data in a single database. They
+ # may, however, read/write data in different tables within that
+ # database.
+ #
+ # ## Locking Read-Write Transactions
+ #
+ # Locking transactions may be used to atomically read-modify-write
+ # data anywhere in a database. This type of transaction is externally
+ # consistent.
+ #
+ # Clients should attempt to minimize the amount of time a transaction
+ # is active. Faster transactions commit with higher probability
+ # and cause less contention. Cloud Spanner attempts to keep read locks
+ # active as long as the transaction continues to do reads, and the
+ # transaction has not been terminated by
+ # Commit or
+ # Rollback. Long periods of
+ # inactivity at the client may cause Cloud Spanner to release a
+ # transaction's locks and abort it.
+ #
+ # Conceptually, a read-write transaction consists of zero or more
+ # reads or SQL statements followed by
+ # Commit. At any time before
+ # Commit, the client can send a
+ # Rollback request to abort the
+ # transaction.
+ #
+ # ### Semantics
+ #
+ # Cloud Spanner can commit the transaction if all read locks it acquired
+ # are still valid at commit time, and it is able to acquire write
+ # locks for all writes. Cloud Spanner can abort the transaction for any
+ # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
+ # that the transaction has not modified any user data in Cloud Spanner.
+ #
+ # Unless the transaction commits, Cloud Spanner makes no guarantees about
+ # how long the transaction's locks were held for. It is an error to
+ # use Cloud Spanner locks for any sort of mutual exclusion other than
+ # between Cloud Spanner transactions themselves.
+ #
+ # ### Retrying Aborted Transactions
+ #
+ # When a transaction aborts, the application can choose to retry the
+ # whole transaction again. To maximize the chances of successfully
+ # committing the retry, the client should execute the retry in the
+ # same session as the original attempt. The original session's lock
+ # priority increases with each consecutive abort, meaning that each
+ # attempt has a slightly better chance of success than the previous.
+ #
+ # Under some circumstances (e.g., many transactions attempting to
+ # modify the same row(s)), a transaction can abort many times in a
+ # short period before successfully committing. Thus, it is not a good
+ # idea to cap the number of retries a transaction can attempt;
+ # instead, it is better to limit the total amount of wall time spent
+ # retrying.
+ #
+ # ### Idle Transactions
+ #
+ # A transaction is considered idle if it has no outstanding reads or
+ # SQL queries and has not started a read or SQL query within the last 10
+ # seconds. Idle transactions can be aborted by Cloud Spanner so that they
+ # don't hold on to locks indefinitely. In that case, the commit will
+ # fail with error `ABORTED`.
+ #
+ # If this behavior is undesirable, periodically executing a simple
+ # SQL query in the transaction (e.g., `SELECT 1`) prevents the
+ # transaction from becoming idle.
+ #
+ # ## Snapshot Read-Only Transactions
+ #
+ # Snapshot read-only transactions provides a simpler method than
+ # locking read-write transactions for doing several consistent
+ # reads. However, this type of transaction does not support writes.
+ #
+ # Snapshot transactions do not take locks. Instead, they work by
+ # choosing a Cloud Spanner timestamp, then executing all reads at that
+ # timestamp. Since they do not acquire locks, they do not block
+ # concurrent read-write transactions.
+ #
+ # Unlike locking read-write transactions, snapshot read-only
+ # transactions never abort. They can fail if the chosen read
+ # timestamp is garbage collected; however, the default garbage
+ # collection policy is generous enough that most applications do not
+ # need to worry about this in practice.
+ #
+ # Snapshot read-only transactions do not need to call
+ # Commit or
+ # Rollback (and in fact are not
+ # permitted to do so).
+ #
+ # To execute a snapshot transaction, the client specifies a timestamp
+ # bound, which tells Cloud Spanner how to choose a read timestamp.
+ #
+ # The types of timestamp bound are:
+ #
+ # - Strong (the default).
+ # - Bounded staleness.
+ # - Exact staleness.
+ #
+ # If the Cloud Spanner database to be read is geographically distributed,
+ # stale read-only transactions can execute more quickly than strong
+ # or read-write transaction, because they are able to execute far
+ # from the leader replica.
+ #
+ # Each type of timestamp bound is discussed in detail below.
+ #
+ # ### Strong
+ #
+ # Strong reads are guaranteed to see the effects of all transactions
+ # that have committed before the start of the read. Furthermore, all
+ # rows yielded by a single read are consistent with each other -- if
+ # any part of the read observes a transaction, all parts of the read
+ # see the transaction.
+ #
+ # Strong reads are not repeatable: two consecutive strong read-only
+ # transactions might return inconsistent results if there are
+ # concurrent writes. If consistency across reads is required, the
+ # reads should be executed within a transaction or at an exact read
+ # timestamp.
+ #
+ # See TransactionOptions.ReadOnly.strong.
+ #
+ # ### Exact Staleness
+ #
+ # These timestamp bounds execute reads at a user-specified
+ # timestamp. Reads at a timestamp are guaranteed to see a consistent
+ # prefix of the global transaction history: they observe
+ # modifications done by all transactions with a commit timestamp <=
+ # the read timestamp, and observe none of the modifications done by
+ # transactions with a larger commit timestamp. They will block until
+ # all conflicting transactions that may be assigned commit timestamps
+ # <= the read timestamp have finished.
+ #
+ # The timestamp can either be expressed as an absolute Cloud Spanner commit
+ # timestamp or a staleness relative to the current time.
+ #
+ # These modes do not require a "negotiation phase" to pick a
+ # timestamp. As a result, they execute slightly faster than the
+ # equivalent boundedly stale concurrency modes. On the other hand,
+ # boundedly stale reads usually return fresher results.
+ #
+ # See TransactionOptions.ReadOnly.read_timestamp and
+ # TransactionOptions.ReadOnly.exact_staleness.
+ #
+ # ### Bounded Staleness
+ #
+ # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
+ # subject to a user-provided staleness bound. Cloud Spanner chooses the
+ # newest timestamp within the staleness bound that allows execution
+ # of the reads at the closest available replica without blocking.
+ #
+ # All rows yielded are consistent with each other -- if any part of
+ # the read observes a transaction, all parts of the read see the
+ # transaction. Boundedly stale reads are not repeatable: two stale
+ # reads, even if they use the same staleness bound, can execute at
+ # different timestamps and thus return inconsistent results.
+ #
+ # Boundedly stale reads execute in two phases: the first phase
+ # negotiates a timestamp among all replicas needed to serve the
+ # read. In the second phase, reads are executed at the negotiated
+ # timestamp.
+ #
+ # As a result of the two phase execution, bounded staleness reads are
+ # usually a little slower than comparable exact staleness
+ # reads. However, they are typically able to return fresher
+ # results, and are more likely to execute at the closest replica.
+ #
+ # Because the timestamp negotiation requires up-front knowledge of
+ # which rows will be read, it can only be used with single-use
+ # read-only transactions.
+ #
+ # See TransactionOptions.ReadOnly.max_staleness and
+ # TransactionOptions.ReadOnly.min_read_timestamp.
+ #
+ # ### Old Read Timestamps and Garbage Collection
+ #
+ # Cloud Spanner continuously garbage collects deleted and overwritten data
+ # in the background to reclaim storage space. This process is known
+ # as "version GC". By default, version GC reclaims versions after they
+ # are one hour old. Because of this, Cloud Spanner cannot perform reads
+ # at read timestamps more than one hour in the past. This
+ # restriction also applies to in-progress reads and/or SQL queries whose
+ # timestamp become too old while executing. Reads and SQL queries with
+ # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
+ #
+ # ## Partitioned DML Transactions
+ #
+ # Partitioned DML transactions are used to execute DML statements with a
+ # different execution strategy that provides different, and often better,
+ # scalability properties for large, table-wide operations than DML in a
+ # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+ # should prefer using ReadWrite transactions.
+ #
+ # Partitioned DML partitions the keyspace and runs the DML statement on each
+ # partition in separate, internal transactions. These transactions commit
+ # automatically when complete, and run independently from one another.
+ #
+ # To reduce lock contention, this execution strategy only acquires read locks
+ # on rows that match the WHERE clause of the statement. Additionally, the
+ # smaller per-partition transactions hold locks for less time.
+ #
+ # That said, Partitioned DML is not a drop-in replacement for standard DML used
+ # in ReadWrite transactions.
+ #
+ # - The DML statement must be fully-partitionable. Specifically, the statement
+ # must be expressible as the union of many statements which each access only
+ # a single row of the table.
+ #
+ # - The statement is not applied atomically to all rows of the table. Rather,
+ # the statement is applied atomically to partitions of the table, in
+ # independent transactions. Secondary index rows are updated atomically
+ # with the base table rows.
+ #
+ # - Partitioned DML does not guarantee exactly-once execution semantics
+ # against a partition. The statement will be applied at least once to each
+ # partition. It is strongly recommended that the DML statement should be
+ # idempotent to avoid unexpected results. For instance, it is potentially
+ # dangerous to run a statement such as
+ # `UPDATE table SET column = column + 1` as it could be run multiple times
+ # against some rows.
+ #
+ # - The partitions are committed automatically - there is no support for
+ # Commit or Rollback. If the call returns an error, or if the client issuing
+ # the ExecuteSql call dies, it is possible that some rows had the statement
+ # executed on them successfully. It is also possible that statement was
+ # never executed against other rows.
+ #
+ # - Partitioned DML transactions may only contain the execution of a single
+ # DML statement via ExecuteSql or ExecuteStreamingSql.
+ #
+ # - If any error is encountered during the execution of the partitioned DML
+ # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
+ # value that cannot be stored due to schema constraints), then the
+ # operation is stopped at that point and an error is returned. It is
+ # possible that at this point, some partitions have been committed (or even
+ # committed multiple times), and other partitions have not been run at all.
+ #
+ # Given the above, Partitioned DML is good fit for large, database-wide,
+ # operations that are idempotent, such as deleting old rows from a very large
+ # table.
+ "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
+ #
+ # Authorization to begin a Partitioned DML transaction requires
+ # `spanner.databases.beginPartitionedDmlTransaction` permission
+ # on the `session` resource.
},
"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
#
@@ -4033,29 +3988,113 @@
# on the `session` resource.
# transaction type has no options.
},
+ "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
+ #
+ # Authorization to begin a read-only transaction requires
+ # `spanner.databases.beginReadOnlyTransaction` permission
+ # on the `session` resource.
+ "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
+ # seconds. Guarantees that all writes that have committed more
+ # than the specified number of seconds ago are visible. Because
+ # Cloud Spanner chooses the exact timestamp, this mode works even if
+ # the client's local clock is substantially skewed from Cloud Spanner
+ # commit timestamps.
+ #
+ # Useful for reading the freshest data available at a nearby
+ # replica, while bounding the possible staleness if the local
+ # replica has fallen behind.
+ #
+ # Note that this option can only be used in single-use
+ # transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
+ "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
+ # the Transaction message that describes the transaction.
+ "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
+ # old. The timestamp is chosen soon after the read is started.
+ #
+ # Guarantees that all writes that have committed more than the
+ # specified number of seconds ago are visible. Because Cloud Spanner
+ # chooses the exact timestamp, this mode works even if the client's
+ # local clock is substantially skewed from Cloud Spanner commit
+ # timestamps.
+ #
+ # Useful for reading at nearby replicas without the distributed
+ # timestamp negotiation overhead of `max_staleness`.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
},
- "id": "A String", # Execute the read or SQL query in a previously-started transaction.
},
+ "queryMode": "A String", # Used to control the amount of debugging information returned in
+ # ResultSetStats. If partition_token is set, query_mode can only
+ # be set to QueryMode.NORMAL.
+ "partitionToken": "A String", # If present, results will be restricted to the specified partition
+ # previously created using PartitionQuery(). There must be an exact
+ # match for the values of fields common to this message and the
+ # PartitionQueryRequest message used to create this partition_token.
"resumeToken": "A String", # If this request is resuming a previously interrupted SQL statement
# execution, `resume_token` should be copied from the last
# PartialResultSet yielded before the interruption. Doing this
# enables the new SQL statement execution to resume where the last one left
# off. The rest of the request parameters must exactly match the
# request that yielded this token.
- "partitionToken": "A String", # If present, results will be restricted to the specified partition
- # previously created using PartitionQuery(). There must be an exact
- # match for the values of fields common to this message and the
- # PartitionQueryRequest message used to create this partition_token.
- "seqno": "A String", # A per-transaction sequence number used to identify this request. This field
- # makes each request idempotent such that if the request is received multiple
- # times, at most one will succeed.
+ "queryOptions": { # Query optimizer configuration. # Query optimizer configuration to use for the given query.
+ "optimizerVersion": "A String", # An option to control the selection of optimizer version.
+ #
+ # This parameter allows individual queries to pick different query
+ # optimizer versions.
+ #
+ # Specifying "latest" as a value instructs Cloud Spanner to use the
+ # latest supported query optimizer version. If not specified, Cloud Spanner
+ # uses optimizer version set at the database level options. Any other
+ # positive integer (from the list of supported optimizer versions)
+ # overrides the default optimizer version for query execution.
+ # The list of supported optimizer versions can be queried from
+ # SPANNER_SYS.SUPPORTED_OPTIMIZER_VERSIONS. Executing a SQL statement
+ # with an invalid optimizer version will fail with a syntax error
+ # (`INVALID_ARGUMENT`) status.
+ # See
+ # https://cloud.google.com/spanner/docs/query-optimizer/manage-query-optimizer
+ # for more information on managing the query optimizer.
+ #
+ # The `optimizer_version` statement hint has precedence over this setting.
+ },
+ "params": { # Parameter names and values that bind to placeholders in the SQL string.
#
- # The sequence number must be monotonically increasing within the
- # transaction. If a request arrives for the first time with an out-of-order
- # sequence number, the transaction may be aborted. Replays of previously
- # handled requests will yield the same response as the first execution.
+ # A parameter placeholder consists of the `@` character followed by the
+ # parameter name (for example, `@firstName`). Parameter names can contain
+ # letters, numbers, and underscores.
#
- # Required for DML statements. Ignored for queries.
+ # Parameters can appear anywhere that a literal value is expected. The same
+ # parameter name can be used more than once, for example:
+ #
+ # `"WHERE id > @msg_id AND id < @msg_id + 100"`
+ #
+ # It is an error to execute a SQL statement with unbound parameters.
+ "a_key": "", # Properties of the object.
+ },
+ "sql": "A String", # Required. The SQL string.
"paramTypes": { # It is not always possible for Cloud Spanner to infer the right SQL type
# from a JSON value. For example, values of type `BYTES` and values
# of type `STRING` both appear in params as JSON strings.
@@ -4091,39 +4130,6 @@
},
},
},
- "sql": "A String", # Required. The SQL string.
- "params": { # Parameter names and values that bind to placeholders in the SQL string.
- #
- # A parameter placeholder consists of the `@` character followed by the
- # parameter name (for example, `@firstName`). Parameter names can contain
- # letters, numbers, and underscores.
- #
- # Parameters can appear anywhere that a literal value is expected. The same
- # parameter name can be used more than once, for example:
- #
- # `"WHERE id > @msg_id AND id < @msg_id + 100"`
- #
- # It is an error to execute a SQL statement with unbound parameters.
- "a_key": "", # Properties of the object.
- },
- "queryOptions": { # Query optimizer configuration. # Query optimizer configuration to use for the given query.
- "optimizerVersion": "A String", # An option to control the selection of optimizer version.
- #
- # This parameter allows individual queries to pick different query
- # optimizer versions.
- #
- # Specifying "latest" as a value instructs Cloud Spanner to use the
- # latest supported query optimizer version. If not specified, Cloud Spanner
- # uses optimizer version set at the database level options. Any other
- # positive integer (from the list of supported optimizer versions)
- # overrides the default optimizer version for query execution.
- # The list of supported optimizer versions can be queried from
- # SPANNER_SYS.SUPPORTED_OPTIMIZER_VERSIONS. Executing a SQL statement
- # with an invalid optimizer version will fail with a syntax error
- # (`INVALID_ARGUMENT`) status.
- #
- # The `optimizer_version` statement hint has precedence over this setting.
- },
}
x__xgafv: string, V1 error format.
@@ -4137,6 +4143,90 @@
{ # Partial results from a streaming read or SQL query. Streaming reads and
# SQL queries better tolerate large result sets, large rows, and large
# values, but are a little trickier to consume.
+ "stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the statement that produced this
+ # streaming result set. These can be requested by setting
+ # ExecuteSqlRequest.query_mode and are sent
+ # only once with the last response in the stream.
+ # This field will also be present in the last response for DML
+ # statements.
+ "rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it
+ # returns a lower bound of the rows modified.
+ "queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
+ "planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
+ # with the plan root. Each PlanNode's `id` corresponds to its index in
+ # `plan_nodes`.
+ { # Node information for nodes appearing in a QueryPlan.plan_nodes.
+ "displayName": "A String", # The display name for the node.
+ "executionStats": { # The execution statistics associated with the node, contained in a group of
+ # key-value pairs. Only present if the plan was returned as a result of a
+ # profile query. For example, number of executions, number of rows/time per
+ # execution etc.
+ "a_key": "", # Properties of the object.
+ },
+ "shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
+ # `SCALAR` PlanNode(s).
+ "subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases
+ # where the `description` string of this node references a `SCALAR`
+ # subquery contained in the expression subtree rooted at this node. The
+ # referenced `SCALAR` subquery may not necessarily be a direct child of
+ # this node.
+ "a_key": 42,
+ },
+ "description": "A String", # A string representation of the expression subtree rooted at this node.
+ },
+ "metadata": { # Attributes relevant to the node contained in a group of key-value pairs.
+ # For example, a Parameter Reference node could have the following
+ # information in its metadata:
+ #
+ # {
+ # "parameter_reference": "param1",
+ # "parameter_type": "array"
+ # }
+ "a_key": "", # Properties of the object.
+ },
+ "childLinks": [ # List of child node `index`es and their relationship to this parent.
+ { # Metadata associated with a parent-child relationship appearing in a
+ # PlanNode.
+ "type": "A String", # The type of the link. For example, in Hash Joins this could be used to
+ # distinguish between the build child and the probe child, or in the case
+ # of the child being an output variable, to represent the tag associated
+ # with the output variable.
+ "variable": "A String", # Only present if the child node is SCALAR and corresponds
+ # to an output variable of the parent node. The field carries the name of
+ # the output variable.
+ # For example, a `TableScan` operator that reads rows from a table will
+ # have child links to the `SCALAR` nodes representing the output variables
+ # created for each column that is read by the operator. The corresponding
+ # `variable` fields will be set to the variable names assigned to the
+ # columns.
+ "childIndex": 42, # The node to which the link points.
+ },
+ ],
+ "index": 42, # The `PlanNode`'s index in node list.
+ "kind": "A String", # Used to determine the type of node. May be needed for visualizing
+ # different kinds of nodes differently. For example, If the node is a
+ # SCALAR node, it will have a condensed representation
+ # which can be used to directly embed a description of the node in its
+ # parent.
+ },
+ ],
+ },
+ "rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.
+ "queryStats": { # Aggregated statistics from the execution of the query. Only present when
+ # the query is profiled. For example, a query could return the statistics as
+ # follows:
+ #
+ # {
+ # "rows_returned": "3",
+ # "elapsed_time": "1.22 secs",
+ # "cpu_time": "1.19 secs"
+ # }
+ "a_key": "", # Properties of the object.
+ },
+ },
+ "chunkedValue": True or False, # If true, then the final value in values is chunked, and must
+ # be combined with more values from subsequent `PartialResultSet`s
+ # to obtain a complete field value.
"values": [ # A streamed result set consists of a stream of values, which might
# be split into many `PartialResultSet` messages to accommodate
# large rows and/or large values. Every N complete values defines a
@@ -4242,6 +4332,12 @@
},
"transaction": { # A transaction. # If the read or SQL query began a transaction as a side-effect, the
# information about the new transaction is yielded here.
+ "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
+ # for the transaction. Not returned by default: see
+ # TransactionOptions.ReadOnly.return_read_timestamp.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
"id": "A String", # `id` may be used to identify the transaction in subsequent
# Read,
# ExecuteSql,
@@ -4250,12 +4346,6 @@
#
# Single-use read-only transactions do not have IDs, because
# single-use transactions do not support multiple requests.
- "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
- # for the transaction. Not returned by default: see
- # TransactionOptions.ReadOnly.return_read_timestamp.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
},
},
"resumeToken": "A String", # Streaming calls might be interrupted for a variety of reasons, such
@@ -4263,90 +4353,6 @@
# be resumed by re-sending the original request and including
# `resume_token`. Note that executing any other transaction in the
# same session invalidates the token.
- "stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the statement that produced this
- # streaming result set. These can be requested by setting
- # ExecuteSqlRequest.query_mode and are sent
- # only once with the last response in the stream.
- # This field will also be present in the last response for DML
- # statements.
- "rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.
- "queryStats": { # Aggregated statistics from the execution of the query. Only present when
- # the query is profiled. For example, a query could return the statistics as
- # follows:
- #
- # {
- # "rows_returned": "3",
- # "elapsed_time": "1.22 secs",
- # "cpu_time": "1.19 secs"
- # }
- "a_key": "", # Properties of the object.
- },
- "rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it
- # returns a lower bound of the rows modified.
- "queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
- "planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
- # with the plan root. Each PlanNode's `id` corresponds to its index in
- # `plan_nodes`.
- { # Node information for nodes appearing in a QueryPlan.plan_nodes.
- "metadata": { # Attributes relevant to the node contained in a group of key-value pairs.
- # For example, a Parameter Reference node could have the following
- # information in its metadata:
- #
- # {
- # "parameter_reference": "param1",
- # "parameter_type": "array"
- # }
- "a_key": "", # Properties of the object.
- },
- "executionStats": { # The execution statistics associated with the node, contained in a group of
- # key-value pairs. Only present if the plan was returned as a result of a
- # profile query. For example, number of executions, number of rows/time per
- # execution etc.
- "a_key": "", # Properties of the object.
- },
- "shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
- # `SCALAR` PlanNode(s).
- "description": "A String", # A string representation of the expression subtree rooted at this node.
- "subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases
- # where the `description` string of this node references a `SCALAR`
- # subquery contained in the expression subtree rooted at this node. The
- # referenced `SCALAR` subquery may not necessarily be a direct child of
- # this node.
- "a_key": 42,
- },
- },
- "index": 42, # The `PlanNode`'s index in node list.
- "kind": "A String", # Used to determine the type of node. May be needed for visualizing
- # different kinds of nodes differently. For example, If the node is a
- # SCALAR node, it will have a condensed representation
- # which can be used to directly embed a description of the node in its
- # parent.
- "displayName": "A String", # The display name for the node.
- "childLinks": [ # List of child node `index`es and their relationship to this parent.
- { # Metadata associated with a parent-child relationship appearing in a
- # PlanNode.
- "variable": "A String", # Only present if the child node is SCALAR and corresponds
- # to an output variable of the parent node. The field carries the name of
- # the output variable.
- # For example, a `TableScan` operator that reads rows from a table will
- # have child links to the `SCALAR` nodes representing the output variables
- # created for each column that is read by the operator. The corresponding
- # `variable` fields will be set to the variable names assigned to the
- # columns.
- "childIndex": 42, # The node to which the link points.
- "type": "A String", # The type of the link. For example, in Hash Joins this could be used to
- # distinguish between the build child and the probe child, or in the case
- # of the child being an output variable, to represent the tag associated
- # with the output variable.
- },
- ],
- },
- ],
- },
- },
- "chunkedValue": True or False, # If true, then the final value in values is chunked, and must
- # be combined with more values from subsequent `PartialResultSet`s
- # to obtain a complete field value.
}</pre>
</div>
@@ -4367,11 +4373,9 @@
An object of the form:
{ # A session in the Cloud Spanner API.
- "approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is
- # typically earlier than the actual last use time.
+ "createTime": "A String", # Output only. The timestamp when the session is created.
"name": "A String", # The name of the session. This is always system-assigned; values provided
# when creating a session are ignored.
- "createTime": "A String", # Output only. The timestamp when the session is created.
"labels": { # The labels for the session.
#
# * Label keys must be between 1 and 63 characters long and must conform to
@@ -4383,11 +4387,13 @@
# See https://goo.gl/xmQnxf for more information on and examples of labels.
"a_key": "A String",
},
+ "approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is
+ # typically earlier than the actual last use time.
}</pre>
</div>
<div class="method">
- <code class="details" id="list">list(database, filter=None, pageToken=None, pageSize=None, x__xgafv=None)</code>
+ <code class="details" id="list">list(database, filter=None, pageSize=None, pageToken=None, x__xgafv=None)</code>
<pre>Lists all sessions in a given database.
Args:
@@ -4402,11 +4408,11 @@
* `labels.env:*` --> The session has the label "env".
* `labels.env:dev` --> The session has the label "env" and the value of
the label contains the string "dev".
+ pageSize: integer, Number of sessions to be returned in the response. If 0 or less, defaults
+to the server's maximum allowed page size.
pageToken: string, If non-empty, `page_token` should contain a
next_page_token from a previous
ListSessionsResponse.
- pageSize: integer, Number of sessions to be returned in the response. If 0 or less, defaults
-to the server's maximum allowed page size.
x__xgafv: string, V1 error format.
Allowed values
1 - v1 error format
@@ -4418,11 +4424,9 @@
{ # The response for ListSessions.
"sessions": [ # The list of requested sessions.
{ # A session in the Cloud Spanner API.
- "approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is
- # typically earlier than the actual last use time.
+ "createTime": "A String", # Output only. The timestamp when the session is created.
"name": "A String", # The name of the session. This is always system-assigned; values provided
# when creating a session are ignored.
- "createTime": "A String", # Output only. The timestamp when the session is created.
"labels": { # The labels for the session.
#
# * Label keys must be between 1 and 63 characters long and must conform to
@@ -4434,6 +4438,8 @@
# See https://goo.gl/xmQnxf for more information on and examples of labels.
"a_key": "A String",
},
+ "approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is
+ # typically earlier than the actual last use time.
},
],
"nextPageToken": "A String", # `next_page_token` can be sent in a subsequent
@@ -4476,6 +4482,37 @@
The object takes the form of:
{ # The request for PartitionQuery
+ "params": { # Parameter names and values that bind to placeholders in the SQL string.
+ #
+ # A parameter placeholder consists of the `@` character followed by the
+ # parameter name (for example, `@firstName`). Parameter names can contain
+ # letters, numbers, and underscores.
+ #
+ # Parameters can appear anywhere that a literal value is expected. The same
+ # parameter name can be used more than once, for example:
+ #
+ # `"WHERE id > @msg_id AND id < @msg_id + 100"`
+ #
+ # It is an error to execute a SQL statement with unbound parameters.
+ "a_key": "", # Properties of the object.
+ },
+ "partitionOptions": { # Options for a PartitionQueryRequest and # Additional options that affect how many partitions are created.
+ # PartitionReadRequest.
+ "maxPartitions": "A String", # **Note:** This hint is currently ignored by PartitionQuery and
+ # PartitionRead requests.
+ #
+ # The desired maximum number of partitions to return. For example, this may
+ # be set to the number of workers available. The default for this option
+ # is currently 10,000. The maximum value is currently 200,000. This is only
+ # a hint. The actual number of partitions returned may be smaller or larger
+ # than this maximum count request.
+ "partitionSizeBytes": "A String", # **Note:** This hint is currently ignored by PartitionQuery and
+ # PartitionRead requests.
+ #
+ # The desired data size for each partition generated. The default for this
+ # option is currently 1 GiB. This is only a hint. The actual size of each
+ # partition may be smaller or larger than this size request.
+ },
"sql": "A String", # Required. The query request to generate partitions for. The request will fail if
# the query is not root partitionable. The query plan of a root
# partitionable query has a single distributed union operator. A distributed
@@ -4486,378 +4523,13 @@
# This must not contain DML commands, such as INSERT, UPDATE, or
# DELETE. Use ExecuteStreamingSql with a
# PartitionedDml transaction for large, partition-friendly DML operations.
- "partitionOptions": { # Options for a PartitionQueryRequest and # Additional options that affect how many partitions are created.
- # PartitionReadRequest.
- "partitionSizeBytes": "A String", # **Note:** This hint is currently ignored by PartitionQuery and
- # PartitionRead requests.
- #
- # The desired data size for each partition generated. The default for this
- # option is currently 1 GiB. This is only a hint. The actual size of each
- # partition may be smaller or larger than this size request.
- "maxPartitions": "A String", # **Note:** This hint is currently ignored by PartitionQuery and
- # PartitionRead requests.
- #
- # The desired maximum number of partitions to return. For example, this may
- # be set to the number of workers available. The default for this option
- # is currently 10,000. The maximum value is currently 200,000. This is only
- # a hint. The actual number of partitions returned may be smaller or larger
- # than this maximum count request.
- },
"transaction": { # This message is used to select the transaction in which a # Read only snapshot transactions are supported, read/write and single use
# transactions are not.
# Read or
# ExecuteSql call runs.
#
# See TransactionOptions for more information about transactions.
- "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
- # This is the most efficient way to execute a transaction that
- # consists of a single SQL query.
- #
- #
- # Each session can have at most one active transaction at a time. After the
- # active transaction is completed, the session can immediately be
- # re-used for the next transaction. It is not necessary to create a
- # new session for each transaction.
- #
- # # Transaction Modes
- #
- # Cloud Spanner supports three transaction modes:
- #
- # 1. Locking read-write. This type of transaction is the only way
- # to write data into Cloud Spanner. These transactions rely on
- # pessimistic locking and, if necessary, two-phase commit.
- # Locking read-write transactions may abort, requiring the
- # application to retry.
- #
- # 2. Snapshot read-only. 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. Snapshot read-only
- # transactions do not need to be committed.
- #
- # 3. Partitioned DML. This type of transaction is used to execute
- # a single Partitioned DML statement. Partitioned DML partitions
- # the key space and runs the DML statement over each partition
- # in parallel using separate, internal transactions that commit
- # independently. Partitioned DML transactions do not need to be
- # committed.
- #
- # For transactions that only read, snapshot read-only transactions
- # provide simpler semantics and are almost always faster. In
- # particular, read-only transactions do not take locks, so they do
- # not conflict with read-write transactions. As a consequence of not
- # taking locks, they also do not abort, so retry loops are not needed.
- #
- # Transactions may only read/write data in a single database. They
- # may, however, read/write data in different tables within that
- # database.
- #
- # ## Locking Read-Write Transactions
- #
- # Locking transactions may be used to atomically read-modify-write
- # data anywhere in a database. This type of transaction is externally
- # consistent.
- #
- # Clients should attempt to minimize the amount of time a transaction
- # is active. Faster transactions commit with higher probability
- # and cause less contention. Cloud Spanner attempts to keep read locks
- # active as long as the transaction continues to do reads, and the
- # transaction has not been terminated by
- # Commit or
- # Rollback. Long periods of
- # inactivity at the client may cause Cloud Spanner to release a
- # transaction's locks and abort it.
- #
- # Conceptually, a read-write transaction consists of zero or more
- # reads or SQL statements followed by
- # Commit. At any time before
- # Commit, the client can send a
- # Rollback request to abort the
- # transaction.
- #
- # ### Semantics
- #
- # Cloud Spanner can commit the transaction if all read locks it acquired
- # are still valid at commit time, and it is able to acquire write
- # locks for all writes. Cloud Spanner can abort the transaction for any
- # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
- # that the transaction has not modified any user data in Cloud Spanner.
- #
- # Unless the transaction commits, Cloud Spanner makes no guarantees about
- # how long the transaction's locks were held for. It is an error to
- # use Cloud Spanner locks for any sort of mutual exclusion other than
- # between Cloud Spanner transactions themselves.
- #
- # ### Retrying Aborted Transactions
- #
- # When a transaction aborts, the application can choose to retry the
- # whole transaction again. To maximize the chances of successfully
- # committing the retry, the client should execute the retry in the
- # same session as the original attempt. The original session's lock
- # priority increases with each consecutive abort, meaning that each
- # attempt has a slightly better chance of success than the previous.
- #
- # Under some circumstances (e.g., many transactions attempting to
- # modify the same row(s)), a transaction can abort many times in a
- # short period before successfully committing. Thus, it is not a good
- # idea to cap the number of retries a transaction can attempt;
- # instead, it is better to limit the total amount of wall time spent
- # retrying.
- #
- # ### Idle Transactions
- #
- # A transaction is considered idle if it has no outstanding reads or
- # SQL queries and has not started a read or SQL query within the last 10
- # seconds. Idle transactions can be aborted by Cloud Spanner so that they
- # don't hold on to locks indefinitely. In that case, the commit will
- # fail with error `ABORTED`.
- #
- # If this behavior is undesirable, periodically executing a simple
- # SQL query in the transaction (e.g., `SELECT 1`) prevents the
- # transaction from becoming idle.
- #
- # ## Snapshot Read-Only Transactions
- #
- # Snapshot read-only transactions provides a simpler method than
- # locking read-write transactions for doing several consistent
- # reads. However, this type of transaction does not support writes.
- #
- # Snapshot transactions do not take locks. Instead, they work by
- # choosing a Cloud Spanner timestamp, then executing all reads at that
- # timestamp. Since they do not acquire locks, they do not block
- # concurrent read-write transactions.
- #
- # Unlike locking read-write transactions, snapshot read-only
- # transactions never abort. They can fail if the chosen read
- # timestamp is garbage collected; however, the default garbage
- # collection policy is generous enough that most applications do not
- # need to worry about this in practice.
- #
- # Snapshot read-only transactions do not need to call
- # Commit or
- # Rollback (and in fact are not
- # permitted to do so).
- #
- # To execute a snapshot transaction, the client specifies a timestamp
- # bound, which tells Cloud Spanner how to choose a read timestamp.
- #
- # The types of timestamp bound are:
- #
- # - Strong (the default).
- # - Bounded staleness.
- # - Exact staleness.
- #
- # If the Cloud Spanner database to be read is geographically distributed,
- # stale read-only transactions can execute more quickly than strong
- # or read-write transaction, because they are able to execute far
- # from the leader replica.
- #
- # Each type of timestamp bound is discussed in detail below.
- #
- # ### Strong
- #
- # Strong reads are guaranteed to see the effects of all transactions
- # that have committed before the start of the read. Furthermore, all
- # rows yielded by a single read are consistent with each other -- if
- # any part of the read observes a transaction, all parts of the read
- # see the transaction.
- #
- # Strong reads are not repeatable: two consecutive strong read-only
- # transactions might return inconsistent results if there are
- # concurrent writes. If consistency across reads is required, the
- # reads should be executed within a transaction or at an exact read
- # timestamp.
- #
- # See TransactionOptions.ReadOnly.strong.
- #
- # ### Exact Staleness
- #
- # These timestamp bounds execute reads at a user-specified
- # timestamp. Reads at a timestamp are guaranteed to see a consistent
- # prefix of the global transaction history: they observe
- # modifications done by all transactions with a commit timestamp <=
- # the read timestamp, and observe none of the modifications done by
- # transactions with a larger commit timestamp. They will block until
- # all conflicting transactions that may be assigned commit timestamps
- # <= the read timestamp have finished.
- #
- # The timestamp can either be expressed as an absolute Cloud Spanner commit
- # timestamp or a staleness relative to the current time.
- #
- # These modes do not require a "negotiation phase" to pick a
- # timestamp. As a result, they execute slightly faster than the
- # equivalent boundedly stale concurrency modes. On the other hand,
- # boundedly stale reads usually return fresher results.
- #
- # See TransactionOptions.ReadOnly.read_timestamp and
- # TransactionOptions.ReadOnly.exact_staleness.
- #
- # ### Bounded Staleness
- #
- # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
- # subject to a user-provided staleness bound. Cloud Spanner chooses the
- # newest timestamp within the staleness bound that allows execution
- # of the reads at the closest available replica without blocking.
- #
- # All rows yielded are consistent with each other -- if any part of
- # the read observes a transaction, all parts of the read see the
- # transaction. Boundedly stale reads are not repeatable: two stale
- # reads, even if they use the same staleness bound, can execute at
- # different timestamps and thus return inconsistent results.
- #
- # Boundedly stale reads execute in two phases: the first phase
- # negotiates a timestamp among all replicas needed to serve the
- # read. In the second phase, reads are executed at the negotiated
- # timestamp.
- #
- # As a result of the two phase execution, bounded staleness reads are
- # usually a little slower than comparable exact staleness
- # reads. However, they are typically able to return fresher
- # results, and are more likely to execute at the closest replica.
- #
- # Because the timestamp negotiation requires up-front knowledge of
- # which rows will be read, it can only be used with single-use
- # read-only transactions.
- #
- # See TransactionOptions.ReadOnly.max_staleness and
- # TransactionOptions.ReadOnly.min_read_timestamp.
- #
- # ### Old Read Timestamps and Garbage Collection
- #
- # Cloud Spanner continuously garbage collects deleted and overwritten data
- # in the background to reclaim storage space. This process is known
- # as "version GC". By default, version GC reclaims versions after they
- # are one hour old. Because of this, Cloud Spanner cannot perform reads
- # at read timestamps more than one hour in the past. This
- # restriction also applies to in-progress reads and/or SQL queries whose
- # timestamp become too old while executing. Reads and SQL queries with
- # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
- #
- # ## Partitioned DML Transactions
- #
- # Partitioned DML transactions are used to execute DML statements with a
- # different execution strategy that provides different, and often better,
- # scalability properties for large, table-wide operations than DML in a
- # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
- # should prefer using ReadWrite transactions.
- #
- # Partitioned DML partitions the keyspace and runs the DML statement on each
- # partition in separate, internal transactions. These transactions commit
- # automatically when complete, and run independently from one another.
- #
- # To reduce lock contention, this execution strategy only acquires read locks
- # on rows that match the WHERE clause of the statement. Additionally, the
- # smaller per-partition transactions hold locks for less time.
- #
- # That said, Partitioned DML is not a drop-in replacement for standard DML used
- # in ReadWrite transactions.
- #
- # - The DML statement must be fully-partitionable. Specifically, the statement
- # must be expressible as the union of many statements which each access only
- # a single row of the table.
- #
- # - The statement is not applied atomically to all rows of the table. Rather,
- # the statement is applied atomically to partitions of the table, in
- # independent transactions. Secondary index rows are updated atomically
- # with the base table rows.
- #
- # - Partitioned DML does not guarantee exactly-once execution semantics
- # against a partition. The statement will be applied at least once to each
- # partition. It is strongly recommended that the DML statement should be
- # idempotent to avoid unexpected results. For instance, it is potentially
- # dangerous to run a statement such as
- # `UPDATE table SET column = column + 1` as it could be run multiple times
- # against some rows.
- #
- # - The partitions are committed automatically - there is no support for
- # Commit or Rollback. If the call returns an error, or if the client issuing
- # the ExecuteSql call dies, it is possible that some rows had the statement
- # executed on them successfully. It is also possible that statement was
- # never executed against other rows.
- #
- # - Partitioned DML transactions may only contain the execution of a single
- # DML statement via ExecuteSql or ExecuteStreamingSql.
- #
- # - If any error is encountered during the execution of the partitioned DML
- # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
- # value that cannot be stored due to schema constraints), then the
- # operation is stopped at that point and an error is returned. It is
- # possible that at this point, some partitions have been committed (or even
- # committed multiple times), and other partitions have not been run at all.
- #
- # Given the above, Partitioned DML is good fit for large, database-wide,
- # operations that are idempotent, such as deleting old rows from a very large
- # table.
- "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
- #
- # Authorization to begin a Partitioned DML transaction requires
- # `spanner.databases.beginPartitionedDmlTransaction` permission
- # on the `session` resource.
- },
- "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
- #
- # Authorization to begin a read-only transaction requires
- # `spanner.databases.beginReadOnlyTransaction` permission
- # on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
- # seconds. Guarantees that all writes that have committed more
- # than the specified number of seconds ago are visible. Because
- # Cloud Spanner chooses the exact timestamp, this mode works even if
- # the client's local clock is substantially skewed from Cloud Spanner
- # commit timestamps.
- #
- # Useful for reading the freshest data available at a nearby
- # replica, while bounding the possible staleness if the local
- # replica has fallen behind.
- #
- # Note that this option can only be used in single-use
- # transactions.
- "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
- # the Transaction message that describes the transaction.
- "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
- # old. The timestamp is chosen soon after the read is started.
- #
- # Guarantees that all writes that have committed more than the
- # specified number of seconds ago are visible. Because Cloud Spanner
- # chooses the exact timestamp, this mode works even if the client's
- # local clock is substantially skewed from Cloud Spanner commit
- # timestamps.
- #
- # Useful for reading at nearby replicas without the distributed
- # timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
- },
- "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
- #
- # Authorization to begin a read-write transaction requires
- # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
- # on the `session` resource.
- # transaction type has no options.
- },
- },
+ "id": "A String", # Execute the read or SQL query in a previously-started transaction.
"begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in
# it. The transaction ID of the new transaction is returned in
# ResultSetMetadata.transaction, which is a Transaction.
@@ -5143,33 +4815,18 @@
# `spanner.databases.beginPartitionedDmlTransaction` permission
# on the `session` resource.
},
+ "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
+ #
+ # Authorization to begin a read-write transaction requires
+ # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
+ # on the `session` resource.
+ # transaction type has no options.
+ },
"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
#
# Authorization to begin a read-only transaction requires
# `spanner.databases.beginReadOnlyTransaction` permission
# on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
# seconds. Guarantees that all writes that have committed more
# than the specified number of seconds ago are visible. Because
@@ -5183,6 +4840,18 @@
#
# Note that this option can only be used in single-use
# transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
# the Transaction message that describes the transaction.
"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
@@ -5196,8 +4865,304 @@
#
# Useful for reading at nearby replicas without the distributed
# timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
+ },
+ "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
+ # This is the most efficient way to execute a transaction that
+ # consists of a single SQL query.
+ #
+ #
+ # Each session can have at most one active transaction at a time. After the
+ # active transaction is completed, the session can immediately be
+ # re-used for the next transaction. It is not necessary to create a
+ # new session for each transaction.
+ #
+ # # Transaction Modes
+ #
+ # Cloud Spanner supports three transaction modes:
+ #
+ # 1. Locking read-write. This type of transaction is the only way
+ # to write data into Cloud Spanner. These transactions rely on
+ # pessimistic locking and, if necessary, two-phase commit.
+ # Locking read-write transactions may abort, requiring the
+ # application to retry.
+ #
+ # 2. Snapshot read-only. 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. Snapshot read-only
+ # transactions do not need to be committed.
+ #
+ # 3. Partitioned DML. This type of transaction is used to execute
+ # a single Partitioned DML statement. Partitioned DML partitions
+ # the key space and runs the DML statement over each partition
+ # in parallel using separate, internal transactions that commit
+ # independently. Partitioned DML transactions do not need to be
+ # committed.
+ #
+ # For transactions that only read, snapshot read-only transactions
+ # provide simpler semantics and are almost always faster. In
+ # particular, read-only transactions do not take locks, so they do
+ # not conflict with read-write transactions. As a consequence of not
+ # taking locks, they also do not abort, so retry loops are not needed.
+ #
+ # Transactions may only read/write data in a single database. They
+ # may, however, read/write data in different tables within that
+ # database.
+ #
+ # ## Locking Read-Write Transactions
+ #
+ # Locking transactions may be used to atomically read-modify-write
+ # data anywhere in a database. This type of transaction is externally
+ # consistent.
+ #
+ # Clients should attempt to minimize the amount of time a transaction
+ # is active. Faster transactions commit with higher probability
+ # and cause less contention. Cloud Spanner attempts to keep read locks
+ # active as long as the transaction continues to do reads, and the
+ # transaction has not been terminated by
+ # Commit or
+ # Rollback. Long periods of
+ # inactivity at the client may cause Cloud Spanner to release a
+ # transaction's locks and abort it.
+ #
+ # Conceptually, a read-write transaction consists of zero or more
+ # reads or SQL statements followed by
+ # Commit. At any time before
+ # Commit, the client can send a
+ # Rollback request to abort the
+ # transaction.
+ #
+ # ### Semantics
+ #
+ # Cloud Spanner can commit the transaction if all read locks it acquired
+ # are still valid at commit time, and it is able to acquire write
+ # locks for all writes. Cloud Spanner can abort the transaction for any
+ # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
+ # that the transaction has not modified any user data in Cloud Spanner.
+ #
+ # Unless the transaction commits, Cloud Spanner makes no guarantees about
+ # how long the transaction's locks were held for. It is an error to
+ # use Cloud Spanner locks for any sort of mutual exclusion other than
+ # between Cloud Spanner transactions themselves.
+ #
+ # ### Retrying Aborted Transactions
+ #
+ # When a transaction aborts, the application can choose to retry the
+ # whole transaction again. To maximize the chances of successfully
+ # committing the retry, the client should execute the retry in the
+ # same session as the original attempt. The original session's lock
+ # priority increases with each consecutive abort, meaning that each
+ # attempt has a slightly better chance of success than the previous.
+ #
+ # Under some circumstances (e.g., many transactions attempting to
+ # modify the same row(s)), a transaction can abort many times in a
+ # short period before successfully committing. Thus, it is not a good
+ # idea to cap the number of retries a transaction can attempt;
+ # instead, it is better to limit the total amount of wall time spent
+ # retrying.
+ #
+ # ### Idle Transactions
+ #
+ # A transaction is considered idle if it has no outstanding reads or
+ # SQL queries and has not started a read or SQL query within the last 10
+ # seconds. Idle transactions can be aborted by Cloud Spanner so that they
+ # don't hold on to locks indefinitely. In that case, the commit will
+ # fail with error `ABORTED`.
+ #
+ # If this behavior is undesirable, periodically executing a simple
+ # SQL query in the transaction (e.g., `SELECT 1`) prevents the
+ # transaction from becoming idle.
+ #
+ # ## Snapshot Read-Only Transactions
+ #
+ # Snapshot read-only transactions provides a simpler method than
+ # locking read-write transactions for doing several consistent
+ # reads. However, this type of transaction does not support writes.
+ #
+ # Snapshot transactions do not take locks. Instead, they work by
+ # choosing a Cloud Spanner timestamp, then executing all reads at that
+ # timestamp. Since they do not acquire locks, they do not block
+ # concurrent read-write transactions.
+ #
+ # Unlike locking read-write transactions, snapshot read-only
+ # transactions never abort. They can fail if the chosen read
+ # timestamp is garbage collected; however, the default garbage
+ # collection policy is generous enough that most applications do not
+ # need to worry about this in practice.
+ #
+ # Snapshot read-only transactions do not need to call
+ # Commit or
+ # Rollback (and in fact are not
+ # permitted to do so).
+ #
+ # To execute a snapshot transaction, the client specifies a timestamp
+ # bound, which tells Cloud Spanner how to choose a read timestamp.
+ #
+ # The types of timestamp bound are:
+ #
+ # - Strong (the default).
+ # - Bounded staleness.
+ # - Exact staleness.
+ #
+ # If the Cloud Spanner database to be read is geographically distributed,
+ # stale read-only transactions can execute more quickly than strong
+ # or read-write transaction, because they are able to execute far
+ # from the leader replica.
+ #
+ # Each type of timestamp bound is discussed in detail below.
+ #
+ # ### Strong
+ #
+ # Strong reads are guaranteed to see the effects of all transactions
+ # that have committed before the start of the read. Furthermore, all
+ # rows yielded by a single read are consistent with each other -- if
+ # any part of the read observes a transaction, all parts of the read
+ # see the transaction.
+ #
+ # Strong reads are not repeatable: two consecutive strong read-only
+ # transactions might return inconsistent results if there are
+ # concurrent writes. If consistency across reads is required, the
+ # reads should be executed within a transaction or at an exact read
+ # timestamp.
+ #
+ # See TransactionOptions.ReadOnly.strong.
+ #
+ # ### Exact Staleness
+ #
+ # These timestamp bounds execute reads at a user-specified
+ # timestamp. Reads at a timestamp are guaranteed to see a consistent
+ # prefix of the global transaction history: they observe
+ # modifications done by all transactions with a commit timestamp <=
+ # the read timestamp, and observe none of the modifications done by
+ # transactions with a larger commit timestamp. They will block until
+ # all conflicting transactions that may be assigned commit timestamps
+ # <= the read timestamp have finished.
+ #
+ # The timestamp can either be expressed as an absolute Cloud Spanner commit
+ # timestamp or a staleness relative to the current time.
+ #
+ # These modes do not require a "negotiation phase" to pick a
+ # timestamp. As a result, they execute slightly faster than the
+ # equivalent boundedly stale concurrency modes. On the other hand,
+ # boundedly stale reads usually return fresher results.
+ #
+ # See TransactionOptions.ReadOnly.read_timestamp and
+ # TransactionOptions.ReadOnly.exact_staleness.
+ #
+ # ### Bounded Staleness
+ #
+ # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
+ # subject to a user-provided staleness bound. Cloud Spanner chooses the
+ # newest timestamp within the staleness bound that allows execution
+ # of the reads at the closest available replica without blocking.
+ #
+ # All rows yielded are consistent with each other -- if any part of
+ # the read observes a transaction, all parts of the read see the
+ # transaction. Boundedly stale reads are not repeatable: two stale
+ # reads, even if they use the same staleness bound, can execute at
+ # different timestamps and thus return inconsistent results.
+ #
+ # Boundedly stale reads execute in two phases: the first phase
+ # negotiates a timestamp among all replicas needed to serve the
+ # read. In the second phase, reads are executed at the negotiated
+ # timestamp.
+ #
+ # As a result of the two phase execution, bounded staleness reads are
+ # usually a little slower than comparable exact staleness
+ # reads. However, they are typically able to return fresher
+ # results, and are more likely to execute at the closest replica.
+ #
+ # Because the timestamp negotiation requires up-front knowledge of
+ # which rows will be read, it can only be used with single-use
+ # read-only transactions.
+ #
+ # See TransactionOptions.ReadOnly.max_staleness and
+ # TransactionOptions.ReadOnly.min_read_timestamp.
+ #
+ # ### Old Read Timestamps and Garbage Collection
+ #
+ # Cloud Spanner continuously garbage collects deleted and overwritten data
+ # in the background to reclaim storage space. This process is known
+ # as "version GC". By default, version GC reclaims versions after they
+ # are one hour old. Because of this, Cloud Spanner cannot perform reads
+ # at read timestamps more than one hour in the past. This
+ # restriction also applies to in-progress reads and/or SQL queries whose
+ # timestamp become too old while executing. Reads and SQL queries with
+ # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
+ #
+ # ## Partitioned DML Transactions
+ #
+ # Partitioned DML transactions are used to execute DML statements with a
+ # different execution strategy that provides different, and often better,
+ # scalability properties for large, table-wide operations than DML in a
+ # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+ # should prefer using ReadWrite transactions.
+ #
+ # Partitioned DML partitions the keyspace and runs the DML statement on each
+ # partition in separate, internal transactions. These transactions commit
+ # automatically when complete, and run independently from one another.
+ #
+ # To reduce lock contention, this execution strategy only acquires read locks
+ # on rows that match the WHERE clause of the statement. Additionally, the
+ # smaller per-partition transactions hold locks for less time.
+ #
+ # That said, Partitioned DML is not a drop-in replacement for standard DML used
+ # in ReadWrite transactions.
+ #
+ # - The DML statement must be fully-partitionable. Specifically, the statement
+ # must be expressible as the union of many statements which each access only
+ # a single row of the table.
+ #
+ # - The statement is not applied atomically to all rows of the table. Rather,
+ # the statement is applied atomically to partitions of the table, in
+ # independent transactions. Secondary index rows are updated atomically
+ # with the base table rows.
+ #
+ # - Partitioned DML does not guarantee exactly-once execution semantics
+ # against a partition. The statement will be applied at least once to each
+ # partition. It is strongly recommended that the DML statement should be
+ # idempotent to avoid unexpected results. For instance, it is potentially
+ # dangerous to run a statement such as
+ # `UPDATE table SET column = column + 1` as it could be run multiple times
+ # against some rows.
+ #
+ # - The partitions are committed automatically - there is no support for
+ # Commit or Rollback. If the call returns an error, or if the client issuing
+ # the ExecuteSql call dies, it is possible that some rows had the statement
+ # executed on them successfully. It is also possible that statement was
+ # never executed against other rows.
+ #
+ # - Partitioned DML transactions may only contain the execution of a single
+ # DML statement via ExecuteSql or ExecuteStreamingSql.
+ #
+ # - If any error is encountered during the execution of the partitioned DML
+ # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
+ # value that cannot be stored due to schema constraints), then the
+ # operation is stopped at that point and an error is returned. It is
+ # possible that at this point, some partitions have been committed (or even
+ # committed multiple times), and other partitions have not been run at all.
+ #
+ # Given the above, Partitioned DML is good fit for large, database-wide,
+ # operations that are idempotent, such as deleting old rows from a very large
+ # table.
+ "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
+ #
+ # Authorization to begin a Partitioned DML transaction requires
+ # `spanner.databases.beginPartitionedDmlTransaction` permission
+ # on the `session` resource.
},
"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
#
@@ -5206,22 +5171,63 @@
# on the `session` resource.
# transaction type has no options.
},
+ "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
+ #
+ # Authorization to begin a read-only transaction requires
+ # `spanner.databases.beginReadOnlyTransaction` permission
+ # on the `session` resource.
+ "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
+ # seconds. Guarantees that all writes that have committed more
+ # than the specified number of seconds ago are visible. Because
+ # Cloud Spanner chooses the exact timestamp, this mode works even if
+ # the client's local clock is substantially skewed from Cloud Spanner
+ # commit timestamps.
+ #
+ # Useful for reading the freshest data available at a nearby
+ # replica, while bounding the possible staleness if the local
+ # replica has fallen behind.
+ #
+ # Note that this option can only be used in single-use
+ # transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
+ "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
+ # the Transaction message that describes the transaction.
+ "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
+ # old. The timestamp is chosen soon after the read is started.
+ #
+ # Guarantees that all writes that have committed more than the
+ # specified number of seconds ago are visible. Because Cloud Spanner
+ # chooses the exact timestamp, this mode works even if the client's
+ # local clock is substantially skewed from Cloud Spanner commit
+ # timestamps.
+ #
+ # Useful for reading at nearby replicas without the distributed
+ # timestamp negotiation overhead of `max_staleness`.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
},
- "id": "A String", # Execute the read or SQL query in a previously-started transaction.
- },
- "params": { # Parameter names and values that bind to placeholders in the SQL string.
- #
- # A parameter placeholder consists of the `@` character followed by the
- # parameter name (for example, `@firstName`). Parameter names can contain
- # letters, numbers, and underscores.
- #
- # Parameters can appear anywhere that a literal value is expected. The same
- # parameter name can be used more than once, for example:
- #
- # `"WHERE id > @msg_id AND id < @msg_id + 100"`
- #
- # It is an error to execute a SQL statement with unbound parameters.
- "a_key": "", # Properties of the object.
},
"paramTypes": { # It is not always possible for Cloud Spanner to infer the right SQL type
# from a JSON value. For example, values of type `BYTES` and values
@@ -5270,22 +5276,6 @@
{ # The response for PartitionQuery
# or PartitionRead
- "transaction": { # A transaction. # Transaction created by this request.
- "id": "A String", # `id` may be used to identify the transaction in subsequent
- # Read,
- # ExecuteSql,
- # Commit, or
- # Rollback calls.
- #
- # Single-use read-only transactions do not have IDs, because
- # single-use transactions do not support multiple requests.
- "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
- # for the transaction. Not returned by default: see
- # TransactionOptions.ReadOnly.return_read_timestamp.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- },
"partitions": [ # Partitions created by this request.
{ # Information returned for each partition returned in a
# PartitionResponse.
@@ -5294,6 +5284,22 @@
# this partition token.
},
],
+ "transaction": { # A transaction. # Transaction created by this request.
+ "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
+ # for the transaction. Not returned by default: see
+ # TransactionOptions.ReadOnly.return_read_timestamp.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "id": "A String", # `id` may be used to identify the transaction in subsequent
+ # Read,
+ # ExecuteSql,
+ # Commit, or
+ # Rollback calls.
+ #
+ # Single-use read-only transactions do not have IDs, because
+ # single-use transactions do not support multiple requests.
+ },
}</pre>
</div>
@@ -5319,734 +5325,6 @@
The object takes the form of:
{ # The request for PartitionRead
- "columns": [ # The columns of table to be returned for each row matching
- # this request.
- "A String",
- ],
- "transaction": { # This message is used to select the transaction in which a # Read only snapshot transactions are supported, read/write and single use
- # transactions are not.
- # Read or
- # ExecuteSql call runs.
- #
- # See TransactionOptions for more information about transactions.
- "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
- # This is the most efficient way to execute a transaction that
- # consists of a single SQL query.
- #
- #
- # Each session can have at most one active transaction at a time. After the
- # active transaction is completed, the session can immediately be
- # re-used for the next transaction. It is not necessary to create a
- # new session for each transaction.
- #
- # # Transaction Modes
- #
- # Cloud Spanner supports three transaction modes:
- #
- # 1. Locking read-write. This type of transaction is the only way
- # to write data into Cloud Spanner. These transactions rely on
- # pessimistic locking and, if necessary, two-phase commit.
- # Locking read-write transactions may abort, requiring the
- # application to retry.
- #
- # 2. Snapshot read-only. 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. Snapshot read-only
- # transactions do not need to be committed.
- #
- # 3. Partitioned DML. This type of transaction is used to execute
- # a single Partitioned DML statement. Partitioned DML partitions
- # the key space and runs the DML statement over each partition
- # in parallel using separate, internal transactions that commit
- # independently. Partitioned DML transactions do not need to be
- # committed.
- #
- # For transactions that only read, snapshot read-only transactions
- # provide simpler semantics and are almost always faster. In
- # particular, read-only transactions do not take locks, so they do
- # not conflict with read-write transactions. As a consequence of not
- # taking locks, they also do not abort, so retry loops are not needed.
- #
- # Transactions may only read/write data in a single database. They
- # may, however, read/write data in different tables within that
- # database.
- #
- # ## Locking Read-Write Transactions
- #
- # Locking transactions may be used to atomically read-modify-write
- # data anywhere in a database. This type of transaction is externally
- # consistent.
- #
- # Clients should attempt to minimize the amount of time a transaction
- # is active. Faster transactions commit with higher probability
- # and cause less contention. Cloud Spanner attempts to keep read locks
- # active as long as the transaction continues to do reads, and the
- # transaction has not been terminated by
- # Commit or
- # Rollback. Long periods of
- # inactivity at the client may cause Cloud Spanner to release a
- # transaction's locks and abort it.
- #
- # Conceptually, a read-write transaction consists of zero or more
- # reads or SQL statements followed by
- # Commit. At any time before
- # Commit, the client can send a
- # Rollback request to abort the
- # transaction.
- #
- # ### Semantics
- #
- # Cloud Spanner can commit the transaction if all read locks it acquired
- # are still valid at commit time, and it is able to acquire write
- # locks for all writes. Cloud Spanner can abort the transaction for any
- # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
- # that the transaction has not modified any user data in Cloud Spanner.
- #
- # Unless the transaction commits, Cloud Spanner makes no guarantees about
- # how long the transaction's locks were held for. It is an error to
- # use Cloud Spanner locks for any sort of mutual exclusion other than
- # between Cloud Spanner transactions themselves.
- #
- # ### Retrying Aborted Transactions
- #
- # When a transaction aborts, the application can choose to retry the
- # whole transaction again. To maximize the chances of successfully
- # committing the retry, the client should execute the retry in the
- # same session as the original attempt. The original session's lock
- # priority increases with each consecutive abort, meaning that each
- # attempt has a slightly better chance of success than the previous.
- #
- # Under some circumstances (e.g., many transactions attempting to
- # modify the same row(s)), a transaction can abort many times in a
- # short period before successfully committing. Thus, it is not a good
- # idea to cap the number of retries a transaction can attempt;
- # instead, it is better to limit the total amount of wall time spent
- # retrying.
- #
- # ### Idle Transactions
- #
- # A transaction is considered idle if it has no outstanding reads or
- # SQL queries and has not started a read or SQL query within the last 10
- # seconds. Idle transactions can be aborted by Cloud Spanner so that they
- # don't hold on to locks indefinitely. In that case, the commit will
- # fail with error `ABORTED`.
- #
- # If this behavior is undesirable, periodically executing a simple
- # SQL query in the transaction (e.g., `SELECT 1`) prevents the
- # transaction from becoming idle.
- #
- # ## Snapshot Read-Only Transactions
- #
- # Snapshot read-only transactions provides a simpler method than
- # locking read-write transactions for doing several consistent
- # reads. However, this type of transaction does not support writes.
- #
- # Snapshot transactions do not take locks. Instead, they work by
- # choosing a Cloud Spanner timestamp, then executing all reads at that
- # timestamp. Since they do not acquire locks, they do not block
- # concurrent read-write transactions.
- #
- # Unlike locking read-write transactions, snapshot read-only
- # transactions never abort. They can fail if the chosen read
- # timestamp is garbage collected; however, the default garbage
- # collection policy is generous enough that most applications do not
- # need to worry about this in practice.
- #
- # Snapshot read-only transactions do not need to call
- # Commit or
- # Rollback (and in fact are not
- # permitted to do so).
- #
- # To execute a snapshot transaction, the client specifies a timestamp
- # bound, which tells Cloud Spanner how to choose a read timestamp.
- #
- # The types of timestamp bound are:
- #
- # - Strong (the default).
- # - Bounded staleness.
- # - Exact staleness.
- #
- # If the Cloud Spanner database to be read is geographically distributed,
- # stale read-only transactions can execute more quickly than strong
- # or read-write transaction, because they are able to execute far
- # from the leader replica.
- #
- # Each type of timestamp bound is discussed in detail below.
- #
- # ### Strong
- #
- # Strong reads are guaranteed to see the effects of all transactions
- # that have committed before the start of the read. Furthermore, all
- # rows yielded by a single read are consistent with each other -- if
- # any part of the read observes a transaction, all parts of the read
- # see the transaction.
- #
- # Strong reads are not repeatable: two consecutive strong read-only
- # transactions might return inconsistent results if there are
- # concurrent writes. If consistency across reads is required, the
- # reads should be executed within a transaction or at an exact read
- # timestamp.
- #
- # See TransactionOptions.ReadOnly.strong.
- #
- # ### Exact Staleness
- #
- # These timestamp bounds execute reads at a user-specified
- # timestamp. Reads at a timestamp are guaranteed to see a consistent
- # prefix of the global transaction history: they observe
- # modifications done by all transactions with a commit timestamp <=
- # the read timestamp, and observe none of the modifications done by
- # transactions with a larger commit timestamp. They will block until
- # all conflicting transactions that may be assigned commit timestamps
- # <= the read timestamp have finished.
- #
- # The timestamp can either be expressed as an absolute Cloud Spanner commit
- # timestamp or a staleness relative to the current time.
- #
- # These modes do not require a "negotiation phase" to pick a
- # timestamp. As a result, they execute slightly faster than the
- # equivalent boundedly stale concurrency modes. On the other hand,
- # boundedly stale reads usually return fresher results.
- #
- # See TransactionOptions.ReadOnly.read_timestamp and
- # TransactionOptions.ReadOnly.exact_staleness.
- #
- # ### Bounded Staleness
- #
- # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
- # subject to a user-provided staleness bound. Cloud Spanner chooses the
- # newest timestamp within the staleness bound that allows execution
- # of the reads at the closest available replica without blocking.
- #
- # All rows yielded are consistent with each other -- if any part of
- # the read observes a transaction, all parts of the read see the
- # transaction. Boundedly stale reads are not repeatable: two stale
- # reads, even if they use the same staleness bound, can execute at
- # different timestamps and thus return inconsistent results.
- #
- # Boundedly stale reads execute in two phases: the first phase
- # negotiates a timestamp among all replicas needed to serve the
- # read. In the second phase, reads are executed at the negotiated
- # timestamp.
- #
- # As a result of the two phase execution, bounded staleness reads are
- # usually a little slower than comparable exact staleness
- # reads. However, they are typically able to return fresher
- # results, and are more likely to execute at the closest replica.
- #
- # Because the timestamp negotiation requires up-front knowledge of
- # which rows will be read, it can only be used with single-use
- # read-only transactions.
- #
- # See TransactionOptions.ReadOnly.max_staleness and
- # TransactionOptions.ReadOnly.min_read_timestamp.
- #
- # ### Old Read Timestamps and Garbage Collection
- #
- # Cloud Spanner continuously garbage collects deleted and overwritten data
- # in the background to reclaim storage space. This process is known
- # as "version GC". By default, version GC reclaims versions after they
- # are one hour old. Because of this, Cloud Spanner cannot perform reads
- # at read timestamps more than one hour in the past. This
- # restriction also applies to in-progress reads and/or SQL queries whose
- # timestamp become too old while executing. Reads and SQL queries with
- # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
- #
- # ## Partitioned DML Transactions
- #
- # Partitioned DML transactions are used to execute DML statements with a
- # different execution strategy that provides different, and often better,
- # scalability properties for large, table-wide operations than DML in a
- # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
- # should prefer using ReadWrite transactions.
- #
- # Partitioned DML partitions the keyspace and runs the DML statement on each
- # partition in separate, internal transactions. These transactions commit
- # automatically when complete, and run independently from one another.
- #
- # To reduce lock contention, this execution strategy only acquires read locks
- # on rows that match the WHERE clause of the statement. Additionally, the
- # smaller per-partition transactions hold locks for less time.
- #
- # That said, Partitioned DML is not a drop-in replacement for standard DML used
- # in ReadWrite transactions.
- #
- # - The DML statement must be fully-partitionable. Specifically, the statement
- # must be expressible as the union of many statements which each access only
- # a single row of the table.
- #
- # - The statement is not applied atomically to all rows of the table. Rather,
- # the statement is applied atomically to partitions of the table, in
- # independent transactions. Secondary index rows are updated atomically
- # with the base table rows.
- #
- # - Partitioned DML does not guarantee exactly-once execution semantics
- # against a partition. The statement will be applied at least once to each
- # partition. It is strongly recommended that the DML statement should be
- # idempotent to avoid unexpected results. For instance, it is potentially
- # dangerous to run a statement such as
- # `UPDATE table SET column = column + 1` as it could be run multiple times
- # against some rows.
- #
- # - The partitions are committed automatically - there is no support for
- # Commit or Rollback. If the call returns an error, or if the client issuing
- # the ExecuteSql call dies, it is possible that some rows had the statement
- # executed on them successfully. It is also possible that statement was
- # never executed against other rows.
- #
- # - Partitioned DML transactions may only contain the execution of a single
- # DML statement via ExecuteSql or ExecuteStreamingSql.
- #
- # - If any error is encountered during the execution of the partitioned DML
- # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
- # value that cannot be stored due to schema constraints), then the
- # operation is stopped at that point and an error is returned. It is
- # possible that at this point, some partitions have been committed (or even
- # committed multiple times), and other partitions have not been run at all.
- #
- # Given the above, Partitioned DML is good fit for large, database-wide,
- # operations that are idempotent, such as deleting old rows from a very large
- # table.
- "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
- #
- # Authorization to begin a Partitioned DML transaction requires
- # `spanner.databases.beginPartitionedDmlTransaction` permission
- # on the `session` resource.
- },
- "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
- #
- # Authorization to begin a read-only transaction requires
- # `spanner.databases.beginReadOnlyTransaction` permission
- # on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
- # seconds. Guarantees that all writes that have committed more
- # than the specified number of seconds ago are visible. Because
- # Cloud Spanner chooses the exact timestamp, this mode works even if
- # the client's local clock is substantially skewed from Cloud Spanner
- # commit timestamps.
- #
- # Useful for reading the freshest data available at a nearby
- # replica, while bounding the possible staleness if the local
- # replica has fallen behind.
- #
- # Note that this option can only be used in single-use
- # transactions.
- "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
- # the Transaction message that describes the transaction.
- "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
- # old. The timestamp is chosen soon after the read is started.
- #
- # Guarantees that all writes that have committed more than the
- # specified number of seconds ago are visible. Because Cloud Spanner
- # chooses the exact timestamp, this mode works even if the client's
- # local clock is substantially skewed from Cloud Spanner commit
- # timestamps.
- #
- # Useful for reading at nearby replicas without the distributed
- # timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
- },
- "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
- #
- # Authorization to begin a read-write transaction requires
- # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
- # on the `session` resource.
- # transaction type has no options.
- },
- },
- "begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in
- # it. The transaction ID of the new transaction is returned in
- # ResultSetMetadata.transaction, which is a Transaction.
- #
- #
- # Each session can have at most one active transaction at a time. After the
- # active transaction is completed, the session can immediately be
- # re-used for the next transaction. It is not necessary to create a
- # new session for each transaction.
- #
- # # Transaction Modes
- #
- # Cloud Spanner supports three transaction modes:
- #
- # 1. Locking read-write. This type of transaction is the only way
- # to write data into Cloud Spanner. These transactions rely on
- # pessimistic locking and, if necessary, two-phase commit.
- # Locking read-write transactions may abort, requiring the
- # application to retry.
- #
- # 2. Snapshot read-only. 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. Snapshot read-only
- # transactions do not need to be committed.
- #
- # 3. Partitioned DML. This type of transaction is used to execute
- # a single Partitioned DML statement. Partitioned DML partitions
- # the key space and runs the DML statement over each partition
- # in parallel using separate, internal transactions that commit
- # independently. Partitioned DML transactions do not need to be
- # committed.
- #
- # For transactions that only read, snapshot read-only transactions
- # provide simpler semantics and are almost always faster. In
- # particular, read-only transactions do not take locks, so they do
- # not conflict with read-write transactions. As a consequence of not
- # taking locks, they also do not abort, so retry loops are not needed.
- #
- # Transactions may only read/write data in a single database. They
- # may, however, read/write data in different tables within that
- # database.
- #
- # ## Locking Read-Write Transactions
- #
- # Locking transactions may be used to atomically read-modify-write
- # data anywhere in a database. This type of transaction is externally
- # consistent.
- #
- # Clients should attempt to minimize the amount of time a transaction
- # is active. Faster transactions commit with higher probability
- # and cause less contention. Cloud Spanner attempts to keep read locks
- # active as long as the transaction continues to do reads, and the
- # transaction has not been terminated by
- # Commit or
- # Rollback. Long periods of
- # inactivity at the client may cause Cloud Spanner to release a
- # transaction's locks and abort it.
- #
- # Conceptually, a read-write transaction consists of zero or more
- # reads or SQL statements followed by
- # Commit. At any time before
- # Commit, the client can send a
- # Rollback request to abort the
- # transaction.
- #
- # ### Semantics
- #
- # Cloud Spanner can commit the transaction if all read locks it acquired
- # are still valid at commit time, and it is able to acquire write
- # locks for all writes. Cloud Spanner can abort the transaction for any
- # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
- # that the transaction has not modified any user data in Cloud Spanner.
- #
- # Unless the transaction commits, Cloud Spanner makes no guarantees about
- # how long the transaction's locks were held for. It is an error to
- # use Cloud Spanner locks for any sort of mutual exclusion other than
- # between Cloud Spanner transactions themselves.
- #
- # ### Retrying Aborted Transactions
- #
- # When a transaction aborts, the application can choose to retry the
- # whole transaction again. To maximize the chances of successfully
- # committing the retry, the client should execute the retry in the
- # same session as the original attempt. The original session's lock
- # priority increases with each consecutive abort, meaning that each
- # attempt has a slightly better chance of success than the previous.
- #
- # Under some circumstances (e.g., many transactions attempting to
- # modify the same row(s)), a transaction can abort many times in a
- # short period before successfully committing. Thus, it is not a good
- # idea to cap the number of retries a transaction can attempt;
- # instead, it is better to limit the total amount of wall time spent
- # retrying.
- #
- # ### Idle Transactions
- #
- # A transaction is considered idle if it has no outstanding reads or
- # SQL queries and has not started a read or SQL query within the last 10
- # seconds. Idle transactions can be aborted by Cloud Spanner so that they
- # don't hold on to locks indefinitely. In that case, the commit will
- # fail with error `ABORTED`.
- #
- # If this behavior is undesirable, periodically executing a simple
- # SQL query in the transaction (e.g., `SELECT 1`) prevents the
- # transaction from becoming idle.
- #
- # ## Snapshot Read-Only Transactions
- #
- # Snapshot read-only transactions provides a simpler method than
- # locking read-write transactions for doing several consistent
- # reads. However, this type of transaction does not support writes.
- #
- # Snapshot transactions do not take locks. Instead, they work by
- # choosing a Cloud Spanner timestamp, then executing all reads at that
- # timestamp. Since they do not acquire locks, they do not block
- # concurrent read-write transactions.
- #
- # Unlike locking read-write transactions, snapshot read-only
- # transactions never abort. They can fail if the chosen read
- # timestamp is garbage collected; however, the default garbage
- # collection policy is generous enough that most applications do not
- # need to worry about this in practice.
- #
- # Snapshot read-only transactions do not need to call
- # Commit or
- # Rollback (and in fact are not
- # permitted to do so).
- #
- # To execute a snapshot transaction, the client specifies a timestamp
- # bound, which tells Cloud Spanner how to choose a read timestamp.
- #
- # The types of timestamp bound are:
- #
- # - Strong (the default).
- # - Bounded staleness.
- # - Exact staleness.
- #
- # If the Cloud Spanner database to be read is geographically distributed,
- # stale read-only transactions can execute more quickly than strong
- # or read-write transaction, because they are able to execute far
- # from the leader replica.
- #
- # Each type of timestamp bound is discussed in detail below.
- #
- # ### Strong
- #
- # Strong reads are guaranteed to see the effects of all transactions
- # that have committed before the start of the read. Furthermore, all
- # rows yielded by a single read are consistent with each other -- if
- # any part of the read observes a transaction, all parts of the read
- # see the transaction.
- #
- # Strong reads are not repeatable: two consecutive strong read-only
- # transactions might return inconsistent results if there are
- # concurrent writes. If consistency across reads is required, the
- # reads should be executed within a transaction or at an exact read
- # timestamp.
- #
- # See TransactionOptions.ReadOnly.strong.
- #
- # ### Exact Staleness
- #
- # These timestamp bounds execute reads at a user-specified
- # timestamp. Reads at a timestamp are guaranteed to see a consistent
- # prefix of the global transaction history: they observe
- # modifications done by all transactions with a commit timestamp <=
- # the read timestamp, and observe none of the modifications done by
- # transactions with a larger commit timestamp. They will block until
- # all conflicting transactions that may be assigned commit timestamps
- # <= the read timestamp have finished.
- #
- # The timestamp can either be expressed as an absolute Cloud Spanner commit
- # timestamp or a staleness relative to the current time.
- #
- # These modes do not require a "negotiation phase" to pick a
- # timestamp. As a result, they execute slightly faster than the
- # equivalent boundedly stale concurrency modes. On the other hand,
- # boundedly stale reads usually return fresher results.
- #
- # See TransactionOptions.ReadOnly.read_timestamp and
- # TransactionOptions.ReadOnly.exact_staleness.
- #
- # ### Bounded Staleness
- #
- # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
- # subject to a user-provided staleness bound. Cloud Spanner chooses the
- # newest timestamp within the staleness bound that allows execution
- # of the reads at the closest available replica without blocking.
- #
- # All rows yielded are consistent with each other -- if any part of
- # the read observes a transaction, all parts of the read see the
- # transaction. Boundedly stale reads are not repeatable: two stale
- # reads, even if they use the same staleness bound, can execute at
- # different timestamps and thus return inconsistent results.
- #
- # Boundedly stale reads execute in two phases: the first phase
- # negotiates a timestamp among all replicas needed to serve the
- # read. In the second phase, reads are executed at the negotiated
- # timestamp.
- #
- # As a result of the two phase execution, bounded staleness reads are
- # usually a little slower than comparable exact staleness
- # reads. However, they are typically able to return fresher
- # results, and are more likely to execute at the closest replica.
- #
- # Because the timestamp negotiation requires up-front knowledge of
- # which rows will be read, it can only be used with single-use
- # read-only transactions.
- #
- # See TransactionOptions.ReadOnly.max_staleness and
- # TransactionOptions.ReadOnly.min_read_timestamp.
- #
- # ### Old Read Timestamps and Garbage Collection
- #
- # Cloud Spanner continuously garbage collects deleted and overwritten data
- # in the background to reclaim storage space. This process is known
- # as "version GC". By default, version GC reclaims versions after they
- # are one hour old. Because of this, Cloud Spanner cannot perform reads
- # at read timestamps more than one hour in the past. This
- # restriction also applies to in-progress reads and/or SQL queries whose
- # timestamp become too old while executing. Reads and SQL queries with
- # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
- #
- # ## Partitioned DML Transactions
- #
- # Partitioned DML transactions are used to execute DML statements with a
- # different execution strategy that provides different, and often better,
- # scalability properties for large, table-wide operations than DML in a
- # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
- # should prefer using ReadWrite transactions.
- #
- # Partitioned DML partitions the keyspace and runs the DML statement on each
- # partition in separate, internal transactions. These transactions commit
- # automatically when complete, and run independently from one another.
- #
- # To reduce lock contention, this execution strategy only acquires read locks
- # on rows that match the WHERE clause of the statement. Additionally, the
- # smaller per-partition transactions hold locks for less time.
- #
- # That said, Partitioned DML is not a drop-in replacement for standard DML used
- # in ReadWrite transactions.
- #
- # - The DML statement must be fully-partitionable. Specifically, the statement
- # must be expressible as the union of many statements which each access only
- # a single row of the table.
- #
- # - The statement is not applied atomically to all rows of the table. Rather,
- # the statement is applied atomically to partitions of the table, in
- # independent transactions. Secondary index rows are updated atomically
- # with the base table rows.
- #
- # - Partitioned DML does not guarantee exactly-once execution semantics
- # against a partition. The statement will be applied at least once to each
- # partition. It is strongly recommended that the DML statement should be
- # idempotent to avoid unexpected results. For instance, it is potentially
- # dangerous to run a statement such as
- # `UPDATE table SET column = column + 1` as it could be run multiple times
- # against some rows.
- #
- # - The partitions are committed automatically - there is no support for
- # Commit or Rollback. If the call returns an error, or if the client issuing
- # the ExecuteSql call dies, it is possible that some rows had the statement
- # executed on them successfully. It is also possible that statement was
- # never executed against other rows.
- #
- # - Partitioned DML transactions may only contain the execution of a single
- # DML statement via ExecuteSql or ExecuteStreamingSql.
- #
- # - If any error is encountered during the execution of the partitioned DML
- # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
- # value that cannot be stored due to schema constraints), then the
- # operation is stopped at that point and an error is returned. It is
- # possible that at this point, some partitions have been committed (or even
- # committed multiple times), and other partitions have not been run at all.
- #
- # Given the above, Partitioned DML is good fit for large, database-wide,
- # operations that are idempotent, such as deleting old rows from a very large
- # table.
- "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
- #
- # Authorization to begin a Partitioned DML transaction requires
- # `spanner.databases.beginPartitionedDmlTransaction` permission
- # on the `session` resource.
- },
- "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
- #
- # Authorization to begin a read-only transaction requires
- # `spanner.databases.beginReadOnlyTransaction` permission
- # on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
- # seconds. Guarantees that all writes that have committed more
- # than the specified number of seconds ago are visible. Because
- # Cloud Spanner chooses the exact timestamp, this mode works even if
- # the client's local clock is substantially skewed from Cloud Spanner
- # commit timestamps.
- #
- # Useful for reading the freshest data available at a nearby
- # replica, while bounding the possible staleness if the local
- # replica has fallen behind.
- #
- # Note that this option can only be used in single-use
- # transactions.
- "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
- # the Transaction message that describes the transaction.
- "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
- # old. The timestamp is chosen soon after the read is started.
- #
- # Guarantees that all writes that have committed more than the
- # specified number of seconds ago are visible. Because Cloud Spanner
- # chooses the exact timestamp, this mode works even if the client's
- # local clock is substantially skewed from Cloud Spanner commit
- # timestamps.
- #
- # Useful for reading at nearby replicas without the distributed
- # timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
- },
- "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
- #
- # Authorization to begin a read-write transaction requires
- # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
- # on the `session` resource.
- # transaction type has no options.
- },
- },
- "id": "A String", # Execute the read or SQL query in a previously-started transaction.
- },
- "table": "A String", # Required. The name of the table in the database to be read.
- "partitionOptions": { # Options for a PartitionQueryRequest and # Additional options that affect how many partitions are created.
- # PartitionReadRequest.
- "partitionSizeBytes": "A String", # **Note:** This hint is currently ignored by PartitionQuery and
- # PartitionRead requests.
- #
- # The desired data size for each partition generated. The default for this
- # option is currently 1 GiB. This is only a hint. The actual size of each
- # partition may be smaller or larger than this size request.
- "maxPartitions": "A String", # **Note:** This hint is currently ignored by PartitionQuery and
- # PartitionRead requests.
- #
- # The desired maximum number of partitions to return. For example, this may
- # be set to the number of workers available. The default for this option
- # is currently 10,000. The maximum value is currently 200,000. This is only
- # a hint. The actual number of partitions returned may be smaller or larger
- # than this maximum count request.
- },
"index": "A String", # If non-empty, the name of an index on table. This index is
# used instead of the table primary key when interpreting key_set
# and sorting result rows. See key_set for further information.
@@ -6152,16 +5430,16 @@
#
# Note that 100 is passed as the start, and 1 is passed as the end,
# because `Key` is a descending column in the schema.
- "endOpen": [ # If the end is open, then the range excludes rows whose first
- # `len(end_open)` key columns exactly match `end_open`.
+ "startOpen": [ # If the start is open, then the range excludes rows whose first
+ # `len(start_open)` key columns exactly match `start_open`.
"",
],
"endClosed": [ # If the end is closed, then the range includes all rows whose
# first `len(end_closed)` key columns exactly match `end_closed`.
"",
],
- "startOpen": [ # If the start is open, then the range excludes rows whose first
- # `len(start_open)` key columns exactly match `start_open`.
+ "endOpen": [ # If the end is open, then the range excludes rows whose first
+ # `len(end_open)` key columns exactly match `end_open`.
"",
],
"startClosed": [ # If the start is closed, then the range includes all rows whose
@@ -6170,9 +5448,6 @@
],
},
],
- "all": True or False, # For convenience `all` can be set to `true` to indicate that this
- # `KeySet` matches all keys in the table or index. Note that any keys
- # specified in `keys` or `ranges` are only yielded once.
"keys": [ # A list of specific keys. Entries in `keys` should have exactly as
# many elements as there are columns in the primary or index key
# with which this `KeySet` is used. Individual key values are
@@ -6181,7 +5456,738 @@
"",
],
],
+ "all": True or False, # For convenience `all` can be set to `true` to indicate that this
+ # `KeySet` matches all keys in the table or index. Note that any keys
+ # specified in `keys` or `ranges` are only yielded once.
},
+ "partitionOptions": { # Options for a PartitionQueryRequest and # Additional options that affect how many partitions are created.
+ # PartitionReadRequest.
+ "maxPartitions": "A String", # **Note:** This hint is currently ignored by PartitionQuery and
+ # PartitionRead requests.
+ #
+ # The desired maximum number of partitions to return. For example, this may
+ # be set to the number of workers available. The default for this option
+ # is currently 10,000. The maximum value is currently 200,000. This is only
+ # a hint. The actual number of partitions returned may be smaller or larger
+ # than this maximum count request.
+ "partitionSizeBytes": "A String", # **Note:** This hint is currently ignored by PartitionQuery and
+ # PartitionRead requests.
+ #
+ # The desired data size for each partition generated. The default for this
+ # option is currently 1 GiB. This is only a hint. The actual size of each
+ # partition may be smaller or larger than this size request.
+ },
+ "transaction": { # This message is used to select the transaction in which a # Read only snapshot transactions are supported, read/write and single use
+ # transactions are not.
+ # Read or
+ # ExecuteSql call runs.
+ #
+ # See TransactionOptions for more information about transactions.
+ "id": "A String", # Execute the read or SQL query in a previously-started transaction.
+ "begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in
+ # it. The transaction ID of the new transaction is returned in
+ # ResultSetMetadata.transaction, which is a Transaction.
+ #
+ #
+ # Each session can have at most one active transaction at a time. After the
+ # active transaction is completed, the session can immediately be
+ # re-used for the next transaction. It is not necessary to create a
+ # new session for each transaction.
+ #
+ # # Transaction Modes
+ #
+ # Cloud Spanner supports three transaction modes:
+ #
+ # 1. Locking read-write. This type of transaction is the only way
+ # to write data into Cloud Spanner. These transactions rely on
+ # pessimistic locking and, if necessary, two-phase commit.
+ # Locking read-write transactions may abort, requiring the
+ # application to retry.
+ #
+ # 2. Snapshot read-only. 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. Snapshot read-only
+ # transactions do not need to be committed.
+ #
+ # 3. Partitioned DML. This type of transaction is used to execute
+ # a single Partitioned DML statement. Partitioned DML partitions
+ # the key space and runs the DML statement over each partition
+ # in parallel using separate, internal transactions that commit
+ # independently. Partitioned DML transactions do not need to be
+ # committed.
+ #
+ # For transactions that only read, snapshot read-only transactions
+ # provide simpler semantics and are almost always faster. In
+ # particular, read-only transactions do not take locks, so they do
+ # not conflict with read-write transactions. As a consequence of not
+ # taking locks, they also do not abort, so retry loops are not needed.
+ #
+ # Transactions may only read/write data in a single database. They
+ # may, however, read/write data in different tables within that
+ # database.
+ #
+ # ## Locking Read-Write Transactions
+ #
+ # Locking transactions may be used to atomically read-modify-write
+ # data anywhere in a database. This type of transaction is externally
+ # consistent.
+ #
+ # Clients should attempt to minimize the amount of time a transaction
+ # is active. Faster transactions commit with higher probability
+ # and cause less contention. Cloud Spanner attempts to keep read locks
+ # active as long as the transaction continues to do reads, and the
+ # transaction has not been terminated by
+ # Commit or
+ # Rollback. Long periods of
+ # inactivity at the client may cause Cloud Spanner to release a
+ # transaction's locks and abort it.
+ #
+ # Conceptually, a read-write transaction consists of zero or more
+ # reads or SQL statements followed by
+ # Commit. At any time before
+ # Commit, the client can send a
+ # Rollback request to abort the
+ # transaction.
+ #
+ # ### Semantics
+ #
+ # Cloud Spanner can commit the transaction if all read locks it acquired
+ # are still valid at commit time, and it is able to acquire write
+ # locks for all writes. Cloud Spanner can abort the transaction for any
+ # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
+ # that the transaction has not modified any user data in Cloud Spanner.
+ #
+ # Unless the transaction commits, Cloud Spanner makes no guarantees about
+ # how long the transaction's locks were held for. It is an error to
+ # use Cloud Spanner locks for any sort of mutual exclusion other than
+ # between Cloud Spanner transactions themselves.
+ #
+ # ### Retrying Aborted Transactions
+ #
+ # When a transaction aborts, the application can choose to retry the
+ # whole transaction again. To maximize the chances of successfully
+ # committing the retry, the client should execute the retry in the
+ # same session as the original attempt. The original session's lock
+ # priority increases with each consecutive abort, meaning that each
+ # attempt has a slightly better chance of success than the previous.
+ #
+ # Under some circumstances (e.g., many transactions attempting to
+ # modify the same row(s)), a transaction can abort many times in a
+ # short period before successfully committing. Thus, it is not a good
+ # idea to cap the number of retries a transaction can attempt;
+ # instead, it is better to limit the total amount of wall time spent
+ # retrying.
+ #
+ # ### Idle Transactions
+ #
+ # A transaction is considered idle if it has no outstanding reads or
+ # SQL queries and has not started a read or SQL query within the last 10
+ # seconds. Idle transactions can be aborted by Cloud Spanner so that they
+ # don't hold on to locks indefinitely. In that case, the commit will
+ # fail with error `ABORTED`.
+ #
+ # If this behavior is undesirable, periodically executing a simple
+ # SQL query in the transaction (e.g., `SELECT 1`) prevents the
+ # transaction from becoming idle.
+ #
+ # ## Snapshot Read-Only Transactions
+ #
+ # Snapshot read-only transactions provides a simpler method than
+ # locking read-write transactions for doing several consistent
+ # reads. However, this type of transaction does not support writes.
+ #
+ # Snapshot transactions do not take locks. Instead, they work by
+ # choosing a Cloud Spanner timestamp, then executing all reads at that
+ # timestamp. Since they do not acquire locks, they do not block
+ # concurrent read-write transactions.
+ #
+ # Unlike locking read-write transactions, snapshot read-only
+ # transactions never abort. They can fail if the chosen read
+ # timestamp is garbage collected; however, the default garbage
+ # collection policy is generous enough that most applications do not
+ # need to worry about this in practice.
+ #
+ # Snapshot read-only transactions do not need to call
+ # Commit or
+ # Rollback (and in fact are not
+ # permitted to do so).
+ #
+ # To execute a snapshot transaction, the client specifies a timestamp
+ # bound, which tells Cloud Spanner how to choose a read timestamp.
+ #
+ # The types of timestamp bound are:
+ #
+ # - Strong (the default).
+ # - Bounded staleness.
+ # - Exact staleness.
+ #
+ # If the Cloud Spanner database to be read is geographically distributed,
+ # stale read-only transactions can execute more quickly than strong
+ # or read-write transaction, because they are able to execute far
+ # from the leader replica.
+ #
+ # Each type of timestamp bound is discussed in detail below.
+ #
+ # ### Strong
+ #
+ # Strong reads are guaranteed to see the effects of all transactions
+ # that have committed before the start of the read. Furthermore, all
+ # rows yielded by a single read are consistent with each other -- if
+ # any part of the read observes a transaction, all parts of the read
+ # see the transaction.
+ #
+ # Strong reads are not repeatable: two consecutive strong read-only
+ # transactions might return inconsistent results if there are
+ # concurrent writes. If consistency across reads is required, the
+ # reads should be executed within a transaction or at an exact read
+ # timestamp.
+ #
+ # See TransactionOptions.ReadOnly.strong.
+ #
+ # ### Exact Staleness
+ #
+ # These timestamp bounds execute reads at a user-specified
+ # timestamp. Reads at a timestamp are guaranteed to see a consistent
+ # prefix of the global transaction history: they observe
+ # modifications done by all transactions with a commit timestamp <=
+ # the read timestamp, and observe none of the modifications done by
+ # transactions with a larger commit timestamp. They will block until
+ # all conflicting transactions that may be assigned commit timestamps
+ # <= the read timestamp have finished.
+ #
+ # The timestamp can either be expressed as an absolute Cloud Spanner commit
+ # timestamp or a staleness relative to the current time.
+ #
+ # These modes do not require a "negotiation phase" to pick a
+ # timestamp. As a result, they execute slightly faster than the
+ # equivalent boundedly stale concurrency modes. On the other hand,
+ # boundedly stale reads usually return fresher results.
+ #
+ # See TransactionOptions.ReadOnly.read_timestamp and
+ # TransactionOptions.ReadOnly.exact_staleness.
+ #
+ # ### Bounded Staleness
+ #
+ # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
+ # subject to a user-provided staleness bound. Cloud Spanner chooses the
+ # newest timestamp within the staleness bound that allows execution
+ # of the reads at the closest available replica without blocking.
+ #
+ # All rows yielded are consistent with each other -- if any part of
+ # the read observes a transaction, all parts of the read see the
+ # transaction. Boundedly stale reads are not repeatable: two stale
+ # reads, even if they use the same staleness bound, can execute at
+ # different timestamps and thus return inconsistent results.
+ #
+ # Boundedly stale reads execute in two phases: the first phase
+ # negotiates a timestamp among all replicas needed to serve the
+ # read. In the second phase, reads are executed at the negotiated
+ # timestamp.
+ #
+ # As a result of the two phase execution, bounded staleness reads are
+ # usually a little slower than comparable exact staleness
+ # reads. However, they are typically able to return fresher
+ # results, and are more likely to execute at the closest replica.
+ #
+ # Because the timestamp negotiation requires up-front knowledge of
+ # which rows will be read, it can only be used with single-use
+ # read-only transactions.
+ #
+ # See TransactionOptions.ReadOnly.max_staleness and
+ # TransactionOptions.ReadOnly.min_read_timestamp.
+ #
+ # ### Old Read Timestamps and Garbage Collection
+ #
+ # Cloud Spanner continuously garbage collects deleted and overwritten data
+ # in the background to reclaim storage space. This process is known
+ # as "version GC". By default, version GC reclaims versions after they
+ # are one hour old. Because of this, Cloud Spanner cannot perform reads
+ # at read timestamps more than one hour in the past. This
+ # restriction also applies to in-progress reads and/or SQL queries whose
+ # timestamp become too old while executing. Reads and SQL queries with
+ # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
+ #
+ # ## Partitioned DML Transactions
+ #
+ # Partitioned DML transactions are used to execute DML statements with a
+ # different execution strategy that provides different, and often better,
+ # scalability properties for large, table-wide operations than DML in a
+ # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+ # should prefer using ReadWrite transactions.
+ #
+ # Partitioned DML partitions the keyspace and runs the DML statement on each
+ # partition in separate, internal transactions. These transactions commit
+ # automatically when complete, and run independently from one another.
+ #
+ # To reduce lock contention, this execution strategy only acquires read locks
+ # on rows that match the WHERE clause of the statement. Additionally, the
+ # smaller per-partition transactions hold locks for less time.
+ #
+ # That said, Partitioned DML is not a drop-in replacement for standard DML used
+ # in ReadWrite transactions.
+ #
+ # - The DML statement must be fully-partitionable. Specifically, the statement
+ # must be expressible as the union of many statements which each access only
+ # a single row of the table.
+ #
+ # - The statement is not applied atomically to all rows of the table. Rather,
+ # the statement is applied atomically to partitions of the table, in
+ # independent transactions. Secondary index rows are updated atomically
+ # with the base table rows.
+ #
+ # - Partitioned DML does not guarantee exactly-once execution semantics
+ # against a partition. The statement will be applied at least once to each
+ # partition. It is strongly recommended that the DML statement should be
+ # idempotent to avoid unexpected results. For instance, it is potentially
+ # dangerous to run a statement such as
+ # `UPDATE table SET column = column + 1` as it could be run multiple times
+ # against some rows.
+ #
+ # - The partitions are committed automatically - there is no support for
+ # Commit or Rollback. If the call returns an error, or if the client issuing
+ # the ExecuteSql call dies, it is possible that some rows had the statement
+ # executed on them successfully. It is also possible that statement was
+ # never executed against other rows.
+ #
+ # - Partitioned DML transactions may only contain the execution of a single
+ # DML statement via ExecuteSql or ExecuteStreamingSql.
+ #
+ # - If any error is encountered during the execution of the partitioned DML
+ # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
+ # value that cannot be stored due to schema constraints), then the
+ # operation is stopped at that point and an error is returned. It is
+ # possible that at this point, some partitions have been committed (or even
+ # committed multiple times), and other partitions have not been run at all.
+ #
+ # Given the above, Partitioned DML is good fit for large, database-wide,
+ # operations that are idempotent, such as deleting old rows from a very large
+ # table.
+ "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
+ #
+ # Authorization to begin a Partitioned DML transaction requires
+ # `spanner.databases.beginPartitionedDmlTransaction` permission
+ # on the `session` resource.
+ },
+ "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
+ #
+ # Authorization to begin a read-write transaction requires
+ # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
+ # on the `session` resource.
+ # transaction type has no options.
+ },
+ "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
+ #
+ # Authorization to begin a read-only transaction requires
+ # `spanner.databases.beginReadOnlyTransaction` permission
+ # on the `session` resource.
+ "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
+ # seconds. Guarantees that all writes that have committed more
+ # than the specified number of seconds ago are visible. Because
+ # Cloud Spanner chooses the exact timestamp, this mode works even if
+ # the client's local clock is substantially skewed from Cloud Spanner
+ # commit timestamps.
+ #
+ # Useful for reading the freshest data available at a nearby
+ # replica, while bounding the possible staleness if the local
+ # replica has fallen behind.
+ #
+ # Note that this option can only be used in single-use
+ # transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
+ "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
+ # the Transaction message that describes the transaction.
+ "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
+ # old. The timestamp is chosen soon after the read is started.
+ #
+ # Guarantees that all writes that have committed more than the
+ # specified number of seconds ago are visible. Because Cloud Spanner
+ # chooses the exact timestamp, this mode works even if the client's
+ # local clock is substantially skewed from Cloud Spanner commit
+ # timestamps.
+ #
+ # Useful for reading at nearby replicas without the distributed
+ # timestamp negotiation overhead of `max_staleness`.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
+ },
+ "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
+ # This is the most efficient way to execute a transaction that
+ # consists of a single SQL query.
+ #
+ #
+ # Each session can have at most one active transaction at a time. After the
+ # active transaction is completed, the session can immediately be
+ # re-used for the next transaction. It is not necessary to create a
+ # new session for each transaction.
+ #
+ # # Transaction Modes
+ #
+ # Cloud Spanner supports three transaction modes:
+ #
+ # 1. Locking read-write. This type of transaction is the only way
+ # to write data into Cloud Spanner. These transactions rely on
+ # pessimistic locking and, if necessary, two-phase commit.
+ # Locking read-write transactions may abort, requiring the
+ # application to retry.
+ #
+ # 2. Snapshot read-only. 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. Snapshot read-only
+ # transactions do not need to be committed.
+ #
+ # 3. Partitioned DML. This type of transaction is used to execute
+ # a single Partitioned DML statement. Partitioned DML partitions
+ # the key space and runs the DML statement over each partition
+ # in parallel using separate, internal transactions that commit
+ # independently. Partitioned DML transactions do not need to be
+ # committed.
+ #
+ # For transactions that only read, snapshot read-only transactions
+ # provide simpler semantics and are almost always faster. In
+ # particular, read-only transactions do not take locks, so they do
+ # not conflict with read-write transactions. As a consequence of not
+ # taking locks, they also do not abort, so retry loops are not needed.
+ #
+ # Transactions may only read/write data in a single database. They
+ # may, however, read/write data in different tables within that
+ # database.
+ #
+ # ## Locking Read-Write Transactions
+ #
+ # Locking transactions may be used to atomically read-modify-write
+ # data anywhere in a database. This type of transaction is externally
+ # consistent.
+ #
+ # Clients should attempt to minimize the amount of time a transaction
+ # is active. Faster transactions commit with higher probability
+ # and cause less contention. Cloud Spanner attempts to keep read locks
+ # active as long as the transaction continues to do reads, and the
+ # transaction has not been terminated by
+ # Commit or
+ # Rollback. Long periods of
+ # inactivity at the client may cause Cloud Spanner to release a
+ # transaction's locks and abort it.
+ #
+ # Conceptually, a read-write transaction consists of zero or more
+ # reads or SQL statements followed by
+ # Commit. At any time before
+ # Commit, the client can send a
+ # Rollback request to abort the
+ # transaction.
+ #
+ # ### Semantics
+ #
+ # Cloud Spanner can commit the transaction if all read locks it acquired
+ # are still valid at commit time, and it is able to acquire write
+ # locks for all writes. Cloud Spanner can abort the transaction for any
+ # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
+ # that the transaction has not modified any user data in Cloud Spanner.
+ #
+ # Unless the transaction commits, Cloud Spanner makes no guarantees about
+ # how long the transaction's locks were held for. It is an error to
+ # use Cloud Spanner locks for any sort of mutual exclusion other than
+ # between Cloud Spanner transactions themselves.
+ #
+ # ### Retrying Aborted Transactions
+ #
+ # When a transaction aborts, the application can choose to retry the
+ # whole transaction again. To maximize the chances of successfully
+ # committing the retry, the client should execute the retry in the
+ # same session as the original attempt. The original session's lock
+ # priority increases with each consecutive abort, meaning that each
+ # attempt has a slightly better chance of success than the previous.
+ #
+ # Under some circumstances (e.g., many transactions attempting to
+ # modify the same row(s)), a transaction can abort many times in a
+ # short period before successfully committing. Thus, it is not a good
+ # idea to cap the number of retries a transaction can attempt;
+ # instead, it is better to limit the total amount of wall time spent
+ # retrying.
+ #
+ # ### Idle Transactions
+ #
+ # A transaction is considered idle if it has no outstanding reads or
+ # SQL queries and has not started a read or SQL query within the last 10
+ # seconds. Idle transactions can be aborted by Cloud Spanner so that they
+ # don't hold on to locks indefinitely. In that case, the commit will
+ # fail with error `ABORTED`.
+ #
+ # If this behavior is undesirable, periodically executing a simple
+ # SQL query in the transaction (e.g., `SELECT 1`) prevents the
+ # transaction from becoming idle.
+ #
+ # ## Snapshot Read-Only Transactions
+ #
+ # Snapshot read-only transactions provides a simpler method than
+ # locking read-write transactions for doing several consistent
+ # reads. However, this type of transaction does not support writes.
+ #
+ # Snapshot transactions do not take locks. Instead, they work by
+ # choosing a Cloud Spanner timestamp, then executing all reads at that
+ # timestamp. Since they do not acquire locks, they do not block
+ # concurrent read-write transactions.
+ #
+ # Unlike locking read-write transactions, snapshot read-only
+ # transactions never abort. They can fail if the chosen read
+ # timestamp is garbage collected; however, the default garbage
+ # collection policy is generous enough that most applications do not
+ # need to worry about this in practice.
+ #
+ # Snapshot read-only transactions do not need to call
+ # Commit or
+ # Rollback (and in fact are not
+ # permitted to do so).
+ #
+ # To execute a snapshot transaction, the client specifies a timestamp
+ # bound, which tells Cloud Spanner how to choose a read timestamp.
+ #
+ # The types of timestamp bound are:
+ #
+ # - Strong (the default).
+ # - Bounded staleness.
+ # - Exact staleness.
+ #
+ # If the Cloud Spanner database to be read is geographically distributed,
+ # stale read-only transactions can execute more quickly than strong
+ # or read-write transaction, because they are able to execute far
+ # from the leader replica.
+ #
+ # Each type of timestamp bound is discussed in detail below.
+ #
+ # ### Strong
+ #
+ # Strong reads are guaranteed to see the effects of all transactions
+ # that have committed before the start of the read. Furthermore, all
+ # rows yielded by a single read are consistent with each other -- if
+ # any part of the read observes a transaction, all parts of the read
+ # see the transaction.
+ #
+ # Strong reads are not repeatable: two consecutive strong read-only
+ # transactions might return inconsistent results if there are
+ # concurrent writes. If consistency across reads is required, the
+ # reads should be executed within a transaction or at an exact read
+ # timestamp.
+ #
+ # See TransactionOptions.ReadOnly.strong.
+ #
+ # ### Exact Staleness
+ #
+ # These timestamp bounds execute reads at a user-specified
+ # timestamp. Reads at a timestamp are guaranteed to see a consistent
+ # prefix of the global transaction history: they observe
+ # modifications done by all transactions with a commit timestamp <=
+ # the read timestamp, and observe none of the modifications done by
+ # transactions with a larger commit timestamp. They will block until
+ # all conflicting transactions that may be assigned commit timestamps
+ # <= the read timestamp have finished.
+ #
+ # The timestamp can either be expressed as an absolute Cloud Spanner commit
+ # timestamp or a staleness relative to the current time.
+ #
+ # These modes do not require a "negotiation phase" to pick a
+ # timestamp. As a result, they execute slightly faster than the
+ # equivalent boundedly stale concurrency modes. On the other hand,
+ # boundedly stale reads usually return fresher results.
+ #
+ # See TransactionOptions.ReadOnly.read_timestamp and
+ # TransactionOptions.ReadOnly.exact_staleness.
+ #
+ # ### Bounded Staleness
+ #
+ # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
+ # subject to a user-provided staleness bound. Cloud Spanner chooses the
+ # newest timestamp within the staleness bound that allows execution
+ # of the reads at the closest available replica without blocking.
+ #
+ # All rows yielded are consistent with each other -- if any part of
+ # the read observes a transaction, all parts of the read see the
+ # transaction. Boundedly stale reads are not repeatable: two stale
+ # reads, even if they use the same staleness bound, can execute at
+ # different timestamps and thus return inconsistent results.
+ #
+ # Boundedly stale reads execute in two phases: the first phase
+ # negotiates a timestamp among all replicas needed to serve the
+ # read. In the second phase, reads are executed at the negotiated
+ # timestamp.
+ #
+ # As a result of the two phase execution, bounded staleness reads are
+ # usually a little slower than comparable exact staleness
+ # reads. However, they are typically able to return fresher
+ # results, and are more likely to execute at the closest replica.
+ #
+ # Because the timestamp negotiation requires up-front knowledge of
+ # which rows will be read, it can only be used with single-use
+ # read-only transactions.
+ #
+ # See TransactionOptions.ReadOnly.max_staleness and
+ # TransactionOptions.ReadOnly.min_read_timestamp.
+ #
+ # ### Old Read Timestamps and Garbage Collection
+ #
+ # Cloud Spanner continuously garbage collects deleted and overwritten data
+ # in the background to reclaim storage space. This process is known
+ # as "version GC". By default, version GC reclaims versions after they
+ # are one hour old. Because of this, Cloud Spanner cannot perform reads
+ # at read timestamps more than one hour in the past. This
+ # restriction also applies to in-progress reads and/or SQL queries whose
+ # timestamp become too old while executing. Reads and SQL queries with
+ # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
+ #
+ # ## Partitioned DML Transactions
+ #
+ # Partitioned DML transactions are used to execute DML statements with a
+ # different execution strategy that provides different, and often better,
+ # scalability properties for large, table-wide operations than DML in a
+ # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+ # should prefer using ReadWrite transactions.
+ #
+ # Partitioned DML partitions the keyspace and runs the DML statement on each
+ # partition in separate, internal transactions. These transactions commit
+ # automatically when complete, and run independently from one another.
+ #
+ # To reduce lock contention, this execution strategy only acquires read locks
+ # on rows that match the WHERE clause of the statement. Additionally, the
+ # smaller per-partition transactions hold locks for less time.
+ #
+ # That said, Partitioned DML is not a drop-in replacement for standard DML used
+ # in ReadWrite transactions.
+ #
+ # - The DML statement must be fully-partitionable. Specifically, the statement
+ # must be expressible as the union of many statements which each access only
+ # a single row of the table.
+ #
+ # - The statement is not applied atomically to all rows of the table. Rather,
+ # the statement is applied atomically to partitions of the table, in
+ # independent transactions. Secondary index rows are updated atomically
+ # with the base table rows.
+ #
+ # - Partitioned DML does not guarantee exactly-once execution semantics
+ # against a partition. The statement will be applied at least once to each
+ # partition. It is strongly recommended that the DML statement should be
+ # idempotent to avoid unexpected results. For instance, it is potentially
+ # dangerous to run a statement such as
+ # `UPDATE table SET column = column + 1` as it could be run multiple times
+ # against some rows.
+ #
+ # - The partitions are committed automatically - there is no support for
+ # Commit or Rollback. If the call returns an error, or if the client issuing
+ # the ExecuteSql call dies, it is possible that some rows had the statement
+ # executed on them successfully. It is also possible that statement was
+ # never executed against other rows.
+ #
+ # - Partitioned DML transactions may only contain the execution of a single
+ # DML statement via ExecuteSql or ExecuteStreamingSql.
+ #
+ # - If any error is encountered during the execution of the partitioned DML
+ # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
+ # value that cannot be stored due to schema constraints), then the
+ # operation is stopped at that point and an error is returned. It is
+ # possible that at this point, some partitions have been committed (or even
+ # committed multiple times), and other partitions have not been run at all.
+ #
+ # Given the above, Partitioned DML is good fit for large, database-wide,
+ # operations that are idempotent, such as deleting old rows from a very large
+ # table.
+ "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
+ #
+ # Authorization to begin a Partitioned DML transaction requires
+ # `spanner.databases.beginPartitionedDmlTransaction` permission
+ # on the `session` resource.
+ },
+ "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
+ #
+ # Authorization to begin a read-write transaction requires
+ # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
+ # on the `session` resource.
+ # transaction type has no options.
+ },
+ "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
+ #
+ # Authorization to begin a read-only transaction requires
+ # `spanner.databases.beginReadOnlyTransaction` permission
+ # on the `session` resource.
+ "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
+ # seconds. Guarantees that all writes that have committed more
+ # than the specified number of seconds ago are visible. Because
+ # Cloud Spanner chooses the exact timestamp, this mode works even if
+ # the client's local clock is substantially skewed from Cloud Spanner
+ # commit timestamps.
+ #
+ # Useful for reading the freshest data available at a nearby
+ # replica, while bounding the possible staleness if the local
+ # replica has fallen behind.
+ #
+ # Note that this option can only be used in single-use
+ # transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
+ "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
+ # the Transaction message that describes the transaction.
+ "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
+ # old. The timestamp is chosen soon after the read is started.
+ #
+ # Guarantees that all writes that have committed more than the
+ # specified number of seconds ago are visible. Because Cloud Spanner
+ # chooses the exact timestamp, this mode works even if the client's
+ # local clock is substantially skewed from Cloud Spanner commit
+ # timestamps.
+ #
+ # Useful for reading at nearby replicas without the distributed
+ # timestamp negotiation overhead of `max_staleness`.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
+ },
+ },
+ "columns": [ # The columns of table to be returned for each row matching
+ # this request.
+ "A String",
+ ],
+ "table": "A String", # Required. The name of the table in the database to be read.
}
x__xgafv: string, V1 error format.
@@ -6194,22 +6200,6 @@
{ # The response for PartitionQuery
# or PartitionRead
- "transaction": { # A transaction. # Transaction created by this request.
- "id": "A String", # `id` may be used to identify the transaction in subsequent
- # Read,
- # ExecuteSql,
- # Commit, or
- # Rollback calls.
- #
- # Single-use read-only transactions do not have IDs, because
- # single-use transactions do not support multiple requests.
- "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
- # for the transaction. Not returned by default: see
- # TransactionOptions.ReadOnly.return_read_timestamp.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- },
"partitions": [ # Partitions created by this request.
{ # Information returned for each partition returned in a
# PartitionResponse.
@@ -6218,6 +6208,22 @@
# this partition token.
},
],
+ "transaction": { # A transaction. # Transaction created by this request.
+ "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
+ # for the transaction. Not returned by default: see
+ # TransactionOptions.ReadOnly.return_read_timestamp.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "id": "A String", # `id` may be used to identify the transaction in subsequent
+ # Read,
+ # ExecuteSql,
+ # Commit, or
+ # Rollback calls.
+ #
+ # Single-use read-only transactions do not have IDs, because
+ # single-use transactions do not support multiple requests.
+ },
}</pre>
</div>
@@ -6244,9 +6250,730 @@
{ # The request for Read and
# StreamingRead.
- "index": "A String", # If non-empty, the name of an index on table. This index is
- # used instead of the table primary key when interpreting key_set
- # and sorting result rows. See key_set for further information.
+ "transaction": { # This message is used to select the transaction in which a # The transaction to use. If none is provided, the default is a
+ # temporary read-only transaction with strong concurrency.
+ # Read or
+ # ExecuteSql call runs.
+ #
+ # See TransactionOptions for more information about transactions.
+ "id": "A String", # Execute the read or SQL query in a previously-started transaction.
+ "begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in
+ # it. The transaction ID of the new transaction is returned in
+ # ResultSetMetadata.transaction, which is a Transaction.
+ #
+ #
+ # Each session can have at most one active transaction at a time. After the
+ # active transaction is completed, the session can immediately be
+ # re-used for the next transaction. It is not necessary to create a
+ # new session for each transaction.
+ #
+ # # Transaction Modes
+ #
+ # Cloud Spanner supports three transaction modes:
+ #
+ # 1. Locking read-write. This type of transaction is the only way
+ # to write data into Cloud Spanner. These transactions rely on
+ # pessimistic locking and, if necessary, two-phase commit.
+ # Locking read-write transactions may abort, requiring the
+ # application to retry.
+ #
+ # 2. Snapshot read-only. 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. Snapshot read-only
+ # transactions do not need to be committed.
+ #
+ # 3. Partitioned DML. This type of transaction is used to execute
+ # a single Partitioned DML statement. Partitioned DML partitions
+ # the key space and runs the DML statement over each partition
+ # in parallel using separate, internal transactions that commit
+ # independently. Partitioned DML transactions do not need to be
+ # committed.
+ #
+ # For transactions that only read, snapshot read-only transactions
+ # provide simpler semantics and are almost always faster. In
+ # particular, read-only transactions do not take locks, so they do
+ # not conflict with read-write transactions. As a consequence of not
+ # taking locks, they also do not abort, so retry loops are not needed.
+ #
+ # Transactions may only read/write data in a single database. They
+ # may, however, read/write data in different tables within that
+ # database.
+ #
+ # ## Locking Read-Write Transactions
+ #
+ # Locking transactions may be used to atomically read-modify-write
+ # data anywhere in a database. This type of transaction is externally
+ # consistent.
+ #
+ # Clients should attempt to minimize the amount of time a transaction
+ # is active. Faster transactions commit with higher probability
+ # and cause less contention. Cloud Spanner attempts to keep read locks
+ # active as long as the transaction continues to do reads, and the
+ # transaction has not been terminated by
+ # Commit or
+ # Rollback. Long periods of
+ # inactivity at the client may cause Cloud Spanner to release a
+ # transaction's locks and abort it.
+ #
+ # Conceptually, a read-write transaction consists of zero or more
+ # reads or SQL statements followed by
+ # Commit. At any time before
+ # Commit, the client can send a
+ # Rollback request to abort the
+ # transaction.
+ #
+ # ### Semantics
+ #
+ # Cloud Spanner can commit the transaction if all read locks it acquired
+ # are still valid at commit time, and it is able to acquire write
+ # locks for all writes. Cloud Spanner can abort the transaction for any
+ # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
+ # that the transaction has not modified any user data in Cloud Spanner.
+ #
+ # Unless the transaction commits, Cloud Spanner makes no guarantees about
+ # how long the transaction's locks were held for. It is an error to
+ # use Cloud Spanner locks for any sort of mutual exclusion other than
+ # between Cloud Spanner transactions themselves.
+ #
+ # ### Retrying Aborted Transactions
+ #
+ # When a transaction aborts, the application can choose to retry the
+ # whole transaction again. To maximize the chances of successfully
+ # committing the retry, the client should execute the retry in the
+ # same session as the original attempt. The original session's lock
+ # priority increases with each consecutive abort, meaning that each
+ # attempt has a slightly better chance of success than the previous.
+ #
+ # Under some circumstances (e.g., many transactions attempting to
+ # modify the same row(s)), a transaction can abort many times in a
+ # short period before successfully committing. Thus, it is not a good
+ # idea to cap the number of retries a transaction can attempt;
+ # instead, it is better to limit the total amount of wall time spent
+ # retrying.
+ #
+ # ### Idle Transactions
+ #
+ # A transaction is considered idle if it has no outstanding reads or
+ # SQL queries and has not started a read or SQL query within the last 10
+ # seconds. Idle transactions can be aborted by Cloud Spanner so that they
+ # don't hold on to locks indefinitely. In that case, the commit will
+ # fail with error `ABORTED`.
+ #
+ # If this behavior is undesirable, periodically executing a simple
+ # SQL query in the transaction (e.g., `SELECT 1`) prevents the
+ # transaction from becoming idle.
+ #
+ # ## Snapshot Read-Only Transactions
+ #
+ # Snapshot read-only transactions provides a simpler method than
+ # locking read-write transactions for doing several consistent
+ # reads. However, this type of transaction does not support writes.
+ #
+ # Snapshot transactions do not take locks. Instead, they work by
+ # choosing a Cloud Spanner timestamp, then executing all reads at that
+ # timestamp. Since they do not acquire locks, they do not block
+ # concurrent read-write transactions.
+ #
+ # Unlike locking read-write transactions, snapshot read-only
+ # transactions never abort. They can fail if the chosen read
+ # timestamp is garbage collected; however, the default garbage
+ # collection policy is generous enough that most applications do not
+ # need to worry about this in practice.
+ #
+ # Snapshot read-only transactions do not need to call
+ # Commit or
+ # Rollback (and in fact are not
+ # permitted to do so).
+ #
+ # To execute a snapshot transaction, the client specifies a timestamp
+ # bound, which tells Cloud Spanner how to choose a read timestamp.
+ #
+ # The types of timestamp bound are:
+ #
+ # - Strong (the default).
+ # - Bounded staleness.
+ # - Exact staleness.
+ #
+ # If the Cloud Spanner database to be read is geographically distributed,
+ # stale read-only transactions can execute more quickly than strong
+ # or read-write transaction, because they are able to execute far
+ # from the leader replica.
+ #
+ # Each type of timestamp bound is discussed in detail below.
+ #
+ # ### Strong
+ #
+ # Strong reads are guaranteed to see the effects of all transactions
+ # that have committed before the start of the read. Furthermore, all
+ # rows yielded by a single read are consistent with each other -- if
+ # any part of the read observes a transaction, all parts of the read
+ # see the transaction.
+ #
+ # Strong reads are not repeatable: two consecutive strong read-only
+ # transactions might return inconsistent results if there are
+ # concurrent writes. If consistency across reads is required, the
+ # reads should be executed within a transaction or at an exact read
+ # timestamp.
+ #
+ # See TransactionOptions.ReadOnly.strong.
+ #
+ # ### Exact Staleness
+ #
+ # These timestamp bounds execute reads at a user-specified
+ # timestamp. Reads at a timestamp are guaranteed to see a consistent
+ # prefix of the global transaction history: they observe
+ # modifications done by all transactions with a commit timestamp <=
+ # the read timestamp, and observe none of the modifications done by
+ # transactions with a larger commit timestamp. They will block until
+ # all conflicting transactions that may be assigned commit timestamps
+ # <= the read timestamp have finished.
+ #
+ # The timestamp can either be expressed as an absolute Cloud Spanner commit
+ # timestamp or a staleness relative to the current time.
+ #
+ # These modes do not require a "negotiation phase" to pick a
+ # timestamp. As a result, they execute slightly faster than the
+ # equivalent boundedly stale concurrency modes. On the other hand,
+ # boundedly stale reads usually return fresher results.
+ #
+ # See TransactionOptions.ReadOnly.read_timestamp and
+ # TransactionOptions.ReadOnly.exact_staleness.
+ #
+ # ### Bounded Staleness
+ #
+ # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
+ # subject to a user-provided staleness bound. Cloud Spanner chooses the
+ # newest timestamp within the staleness bound that allows execution
+ # of the reads at the closest available replica without blocking.
+ #
+ # All rows yielded are consistent with each other -- if any part of
+ # the read observes a transaction, all parts of the read see the
+ # transaction. Boundedly stale reads are not repeatable: two stale
+ # reads, even if they use the same staleness bound, can execute at
+ # different timestamps and thus return inconsistent results.
+ #
+ # Boundedly stale reads execute in two phases: the first phase
+ # negotiates a timestamp among all replicas needed to serve the
+ # read. In the second phase, reads are executed at the negotiated
+ # timestamp.
+ #
+ # As a result of the two phase execution, bounded staleness reads are
+ # usually a little slower than comparable exact staleness
+ # reads. However, they are typically able to return fresher
+ # results, and are more likely to execute at the closest replica.
+ #
+ # Because the timestamp negotiation requires up-front knowledge of
+ # which rows will be read, it can only be used with single-use
+ # read-only transactions.
+ #
+ # See TransactionOptions.ReadOnly.max_staleness and
+ # TransactionOptions.ReadOnly.min_read_timestamp.
+ #
+ # ### Old Read Timestamps and Garbage Collection
+ #
+ # Cloud Spanner continuously garbage collects deleted and overwritten data
+ # in the background to reclaim storage space. This process is known
+ # as "version GC". By default, version GC reclaims versions after they
+ # are one hour old. Because of this, Cloud Spanner cannot perform reads
+ # at read timestamps more than one hour in the past. This
+ # restriction also applies to in-progress reads and/or SQL queries whose
+ # timestamp become too old while executing. Reads and SQL queries with
+ # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
+ #
+ # ## Partitioned DML Transactions
+ #
+ # Partitioned DML transactions are used to execute DML statements with a
+ # different execution strategy that provides different, and often better,
+ # scalability properties for large, table-wide operations than DML in a
+ # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+ # should prefer using ReadWrite transactions.
+ #
+ # Partitioned DML partitions the keyspace and runs the DML statement on each
+ # partition in separate, internal transactions. These transactions commit
+ # automatically when complete, and run independently from one another.
+ #
+ # To reduce lock contention, this execution strategy only acquires read locks
+ # on rows that match the WHERE clause of the statement. Additionally, the
+ # smaller per-partition transactions hold locks for less time.
+ #
+ # That said, Partitioned DML is not a drop-in replacement for standard DML used
+ # in ReadWrite transactions.
+ #
+ # - The DML statement must be fully-partitionable. Specifically, the statement
+ # must be expressible as the union of many statements which each access only
+ # a single row of the table.
+ #
+ # - The statement is not applied atomically to all rows of the table. Rather,
+ # the statement is applied atomically to partitions of the table, in
+ # independent transactions. Secondary index rows are updated atomically
+ # with the base table rows.
+ #
+ # - Partitioned DML does not guarantee exactly-once execution semantics
+ # against a partition. The statement will be applied at least once to each
+ # partition. It is strongly recommended that the DML statement should be
+ # idempotent to avoid unexpected results. For instance, it is potentially
+ # dangerous to run a statement such as
+ # `UPDATE table SET column = column + 1` as it could be run multiple times
+ # against some rows.
+ #
+ # - The partitions are committed automatically - there is no support for
+ # Commit or Rollback. If the call returns an error, or if the client issuing
+ # the ExecuteSql call dies, it is possible that some rows had the statement
+ # executed on them successfully. It is also possible that statement was
+ # never executed against other rows.
+ #
+ # - Partitioned DML transactions may only contain the execution of a single
+ # DML statement via ExecuteSql or ExecuteStreamingSql.
+ #
+ # - If any error is encountered during the execution of the partitioned DML
+ # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
+ # value that cannot be stored due to schema constraints), then the
+ # operation is stopped at that point and an error is returned. It is
+ # possible that at this point, some partitions have been committed (or even
+ # committed multiple times), and other partitions have not been run at all.
+ #
+ # Given the above, Partitioned DML is good fit for large, database-wide,
+ # operations that are idempotent, such as deleting old rows from a very large
+ # table.
+ "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
+ #
+ # Authorization to begin a Partitioned DML transaction requires
+ # `spanner.databases.beginPartitionedDmlTransaction` permission
+ # on the `session` resource.
+ },
+ "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
+ #
+ # Authorization to begin a read-write transaction requires
+ # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
+ # on the `session` resource.
+ # transaction type has no options.
+ },
+ "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
+ #
+ # Authorization to begin a read-only transaction requires
+ # `spanner.databases.beginReadOnlyTransaction` permission
+ # on the `session` resource.
+ "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
+ # seconds. Guarantees that all writes that have committed more
+ # than the specified number of seconds ago are visible. Because
+ # Cloud Spanner chooses the exact timestamp, this mode works even if
+ # the client's local clock is substantially skewed from Cloud Spanner
+ # commit timestamps.
+ #
+ # Useful for reading the freshest data available at a nearby
+ # replica, while bounding the possible staleness if the local
+ # replica has fallen behind.
+ #
+ # Note that this option can only be used in single-use
+ # transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
+ "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
+ # the Transaction message that describes the transaction.
+ "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
+ # old. The timestamp is chosen soon after the read is started.
+ #
+ # Guarantees that all writes that have committed more than the
+ # specified number of seconds ago are visible. Because Cloud Spanner
+ # chooses the exact timestamp, this mode works even if the client's
+ # local clock is substantially skewed from Cloud Spanner commit
+ # timestamps.
+ #
+ # Useful for reading at nearby replicas without the distributed
+ # timestamp negotiation overhead of `max_staleness`.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
+ },
+ "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
+ # This is the most efficient way to execute a transaction that
+ # consists of a single SQL query.
+ #
+ #
+ # Each session can have at most one active transaction at a time. After the
+ # active transaction is completed, the session can immediately be
+ # re-used for the next transaction. It is not necessary to create a
+ # new session for each transaction.
+ #
+ # # Transaction Modes
+ #
+ # Cloud Spanner supports three transaction modes:
+ #
+ # 1. Locking read-write. This type of transaction is the only way
+ # to write data into Cloud Spanner. These transactions rely on
+ # pessimistic locking and, if necessary, two-phase commit.
+ # Locking read-write transactions may abort, requiring the
+ # application to retry.
+ #
+ # 2. Snapshot read-only. 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. Snapshot read-only
+ # transactions do not need to be committed.
+ #
+ # 3. Partitioned DML. This type of transaction is used to execute
+ # a single Partitioned DML statement. Partitioned DML partitions
+ # the key space and runs the DML statement over each partition
+ # in parallel using separate, internal transactions that commit
+ # independently. Partitioned DML transactions do not need to be
+ # committed.
+ #
+ # For transactions that only read, snapshot read-only transactions
+ # provide simpler semantics and are almost always faster. In
+ # particular, read-only transactions do not take locks, so they do
+ # not conflict with read-write transactions. As a consequence of not
+ # taking locks, they also do not abort, so retry loops are not needed.
+ #
+ # Transactions may only read/write data in a single database. They
+ # may, however, read/write data in different tables within that
+ # database.
+ #
+ # ## Locking Read-Write Transactions
+ #
+ # Locking transactions may be used to atomically read-modify-write
+ # data anywhere in a database. This type of transaction is externally
+ # consistent.
+ #
+ # Clients should attempt to minimize the amount of time a transaction
+ # is active. Faster transactions commit with higher probability
+ # and cause less contention. Cloud Spanner attempts to keep read locks
+ # active as long as the transaction continues to do reads, and the
+ # transaction has not been terminated by
+ # Commit or
+ # Rollback. Long periods of
+ # inactivity at the client may cause Cloud Spanner to release a
+ # transaction's locks and abort it.
+ #
+ # Conceptually, a read-write transaction consists of zero or more
+ # reads or SQL statements followed by
+ # Commit. At any time before
+ # Commit, the client can send a
+ # Rollback request to abort the
+ # transaction.
+ #
+ # ### Semantics
+ #
+ # Cloud Spanner can commit the transaction if all read locks it acquired
+ # are still valid at commit time, and it is able to acquire write
+ # locks for all writes. Cloud Spanner can abort the transaction for any
+ # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
+ # that the transaction has not modified any user data in Cloud Spanner.
+ #
+ # Unless the transaction commits, Cloud Spanner makes no guarantees about
+ # how long the transaction's locks were held for. It is an error to
+ # use Cloud Spanner locks for any sort of mutual exclusion other than
+ # between Cloud Spanner transactions themselves.
+ #
+ # ### Retrying Aborted Transactions
+ #
+ # When a transaction aborts, the application can choose to retry the
+ # whole transaction again. To maximize the chances of successfully
+ # committing the retry, the client should execute the retry in the
+ # same session as the original attempt. The original session's lock
+ # priority increases with each consecutive abort, meaning that each
+ # attempt has a slightly better chance of success than the previous.
+ #
+ # Under some circumstances (e.g., many transactions attempting to
+ # modify the same row(s)), a transaction can abort many times in a
+ # short period before successfully committing. Thus, it is not a good
+ # idea to cap the number of retries a transaction can attempt;
+ # instead, it is better to limit the total amount of wall time spent
+ # retrying.
+ #
+ # ### Idle Transactions
+ #
+ # A transaction is considered idle if it has no outstanding reads or
+ # SQL queries and has not started a read or SQL query within the last 10
+ # seconds. Idle transactions can be aborted by Cloud Spanner so that they
+ # don't hold on to locks indefinitely. In that case, the commit will
+ # fail with error `ABORTED`.
+ #
+ # If this behavior is undesirable, periodically executing a simple
+ # SQL query in the transaction (e.g., `SELECT 1`) prevents the
+ # transaction from becoming idle.
+ #
+ # ## Snapshot Read-Only Transactions
+ #
+ # Snapshot read-only transactions provides a simpler method than
+ # locking read-write transactions for doing several consistent
+ # reads. However, this type of transaction does not support writes.
+ #
+ # Snapshot transactions do not take locks. Instead, they work by
+ # choosing a Cloud Spanner timestamp, then executing all reads at that
+ # timestamp. Since they do not acquire locks, they do not block
+ # concurrent read-write transactions.
+ #
+ # Unlike locking read-write transactions, snapshot read-only
+ # transactions never abort. They can fail if the chosen read
+ # timestamp is garbage collected; however, the default garbage
+ # collection policy is generous enough that most applications do not
+ # need to worry about this in practice.
+ #
+ # Snapshot read-only transactions do not need to call
+ # Commit or
+ # Rollback (and in fact are not
+ # permitted to do so).
+ #
+ # To execute a snapshot transaction, the client specifies a timestamp
+ # bound, which tells Cloud Spanner how to choose a read timestamp.
+ #
+ # The types of timestamp bound are:
+ #
+ # - Strong (the default).
+ # - Bounded staleness.
+ # - Exact staleness.
+ #
+ # If the Cloud Spanner database to be read is geographically distributed,
+ # stale read-only transactions can execute more quickly than strong
+ # or read-write transaction, because they are able to execute far
+ # from the leader replica.
+ #
+ # Each type of timestamp bound is discussed in detail below.
+ #
+ # ### Strong
+ #
+ # Strong reads are guaranteed to see the effects of all transactions
+ # that have committed before the start of the read. Furthermore, all
+ # rows yielded by a single read are consistent with each other -- if
+ # any part of the read observes a transaction, all parts of the read
+ # see the transaction.
+ #
+ # Strong reads are not repeatable: two consecutive strong read-only
+ # transactions might return inconsistent results if there are
+ # concurrent writes. If consistency across reads is required, the
+ # reads should be executed within a transaction or at an exact read
+ # timestamp.
+ #
+ # See TransactionOptions.ReadOnly.strong.
+ #
+ # ### Exact Staleness
+ #
+ # These timestamp bounds execute reads at a user-specified
+ # timestamp. Reads at a timestamp are guaranteed to see a consistent
+ # prefix of the global transaction history: they observe
+ # modifications done by all transactions with a commit timestamp <=
+ # the read timestamp, and observe none of the modifications done by
+ # transactions with a larger commit timestamp. They will block until
+ # all conflicting transactions that may be assigned commit timestamps
+ # <= the read timestamp have finished.
+ #
+ # The timestamp can either be expressed as an absolute Cloud Spanner commit
+ # timestamp or a staleness relative to the current time.
+ #
+ # These modes do not require a "negotiation phase" to pick a
+ # timestamp. As a result, they execute slightly faster than the
+ # equivalent boundedly stale concurrency modes. On the other hand,
+ # boundedly stale reads usually return fresher results.
+ #
+ # See TransactionOptions.ReadOnly.read_timestamp and
+ # TransactionOptions.ReadOnly.exact_staleness.
+ #
+ # ### Bounded Staleness
+ #
+ # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
+ # subject to a user-provided staleness bound. Cloud Spanner chooses the
+ # newest timestamp within the staleness bound that allows execution
+ # of the reads at the closest available replica without blocking.
+ #
+ # All rows yielded are consistent with each other -- if any part of
+ # the read observes a transaction, all parts of the read see the
+ # transaction. Boundedly stale reads are not repeatable: two stale
+ # reads, even if they use the same staleness bound, can execute at
+ # different timestamps and thus return inconsistent results.
+ #
+ # Boundedly stale reads execute in two phases: the first phase
+ # negotiates a timestamp among all replicas needed to serve the
+ # read. In the second phase, reads are executed at the negotiated
+ # timestamp.
+ #
+ # As a result of the two phase execution, bounded staleness reads are
+ # usually a little slower than comparable exact staleness
+ # reads. However, they are typically able to return fresher
+ # results, and are more likely to execute at the closest replica.
+ #
+ # Because the timestamp negotiation requires up-front knowledge of
+ # which rows will be read, it can only be used with single-use
+ # read-only transactions.
+ #
+ # See TransactionOptions.ReadOnly.max_staleness and
+ # TransactionOptions.ReadOnly.min_read_timestamp.
+ #
+ # ### Old Read Timestamps and Garbage Collection
+ #
+ # Cloud Spanner continuously garbage collects deleted and overwritten data
+ # in the background to reclaim storage space. This process is known
+ # as "version GC". By default, version GC reclaims versions after they
+ # are one hour old. Because of this, Cloud Spanner cannot perform reads
+ # at read timestamps more than one hour in the past. This
+ # restriction also applies to in-progress reads and/or SQL queries whose
+ # timestamp become too old while executing. Reads and SQL queries with
+ # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
+ #
+ # ## Partitioned DML Transactions
+ #
+ # Partitioned DML transactions are used to execute DML statements with a
+ # different execution strategy that provides different, and often better,
+ # scalability properties for large, table-wide operations than DML in a
+ # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+ # should prefer using ReadWrite transactions.
+ #
+ # Partitioned DML partitions the keyspace and runs the DML statement on each
+ # partition in separate, internal transactions. These transactions commit
+ # automatically when complete, and run independently from one another.
+ #
+ # To reduce lock contention, this execution strategy only acquires read locks
+ # on rows that match the WHERE clause of the statement. Additionally, the
+ # smaller per-partition transactions hold locks for less time.
+ #
+ # That said, Partitioned DML is not a drop-in replacement for standard DML used
+ # in ReadWrite transactions.
+ #
+ # - The DML statement must be fully-partitionable. Specifically, the statement
+ # must be expressible as the union of many statements which each access only
+ # a single row of the table.
+ #
+ # - The statement is not applied atomically to all rows of the table. Rather,
+ # the statement is applied atomically to partitions of the table, in
+ # independent transactions. Secondary index rows are updated atomically
+ # with the base table rows.
+ #
+ # - Partitioned DML does not guarantee exactly-once execution semantics
+ # against a partition. The statement will be applied at least once to each
+ # partition. It is strongly recommended that the DML statement should be
+ # idempotent to avoid unexpected results. For instance, it is potentially
+ # dangerous to run a statement such as
+ # `UPDATE table SET column = column + 1` as it could be run multiple times
+ # against some rows.
+ #
+ # - The partitions are committed automatically - there is no support for
+ # Commit or Rollback. If the call returns an error, or if the client issuing
+ # the ExecuteSql call dies, it is possible that some rows had the statement
+ # executed on them successfully. It is also possible that statement was
+ # never executed against other rows.
+ #
+ # - Partitioned DML transactions may only contain the execution of a single
+ # DML statement via ExecuteSql or ExecuteStreamingSql.
+ #
+ # - If any error is encountered during the execution of the partitioned DML
+ # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
+ # value that cannot be stored due to schema constraints), then the
+ # operation is stopped at that point and an error is returned. It is
+ # possible that at this point, some partitions have been committed (or even
+ # committed multiple times), and other partitions have not been run at all.
+ #
+ # Given the above, Partitioned DML is good fit for large, database-wide,
+ # operations that are idempotent, such as deleting old rows from a very large
+ # table.
+ "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
+ #
+ # Authorization to begin a Partitioned DML transaction requires
+ # `spanner.databases.beginPartitionedDmlTransaction` permission
+ # on the `session` resource.
+ },
+ "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
+ #
+ # Authorization to begin a read-write transaction requires
+ # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
+ # on the `session` resource.
+ # transaction type has no options.
+ },
+ "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
+ #
+ # Authorization to begin a read-only transaction requires
+ # `spanner.databases.beginReadOnlyTransaction` permission
+ # on the `session` resource.
+ "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
+ # seconds. Guarantees that all writes that have committed more
+ # than the specified number of seconds ago are visible. Because
+ # Cloud Spanner chooses the exact timestamp, this mode works even if
+ # the client's local clock is substantially skewed from Cloud Spanner
+ # commit timestamps.
+ #
+ # Useful for reading the freshest data available at a nearby
+ # replica, while bounding the possible staleness if the local
+ # replica has fallen behind.
+ #
+ # Note that this option can only be used in single-use
+ # transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
+ "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
+ # the Transaction message that describes the transaction.
+ "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
+ # old. The timestamp is chosen soon after the read is started.
+ #
+ # Guarantees that all writes that have committed more than the
+ # specified number of seconds ago are visible. Because Cloud Spanner
+ # chooses the exact timestamp, this mode works even if the client's
+ # local clock is substantially skewed from Cloud Spanner commit
+ # timestamps.
+ #
+ # Useful for reading at nearby replicas without the distributed
+ # timestamp negotiation overhead of `max_staleness`.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
+ },
+ },
+ "partitionToken": "A String", # If present, results will be restricted to the specified partition
+ # previously created using PartitionRead(). There must be an exact
+ # match for the values of fields common to this message and the
+ # PartitionReadRequest message used to create this partition_token.
+ "columns": [ # Required. The columns of table to be returned for each row matching
+ # this request.
+ "A String",
+ ],
+ "limit": "A String", # If greater than zero, only the first `limit` rows are yielded. If `limit`
+ # is zero, the default is no limit. A limit cannot be specified if
+ # `partition_token` is set.
+ "table": "A String", # Required. The name of the table in the database to be read.
+ "resumeToken": "A String", # If this request is resuming a previously interrupted read,
+ # `resume_token` should be copied from the last
+ # PartialResultSet yielded before the interruption. Doing this
+ # enables the new read to resume where the last read left off. The
+ # rest of the request parameters must exactly match the request
+ # that yielded this token.
"keySet": { # `KeySet` defines a collection of Cloud Spanner keys and/or key ranges. All # Required. `key_set` identifies the rows to be yielded. `key_set` names the
# primary keys of the rows in table to be yielded, unless index
# is present. If index is present, then key_set instead names
@@ -6354,16 +7081,16 @@
#
# Note that 100 is passed as the start, and 1 is passed as the end,
# because `Key` is a descending column in the schema.
- "endOpen": [ # If the end is open, then the range excludes rows whose first
- # `len(end_open)` key columns exactly match `end_open`.
+ "startOpen": [ # If the start is open, then the range excludes rows whose first
+ # `len(start_open)` key columns exactly match `start_open`.
"",
],
"endClosed": [ # If the end is closed, then the range includes all rows whose
# first `len(end_closed)` key columns exactly match `end_closed`.
"",
],
- "startOpen": [ # If the start is open, then the range excludes rows whose first
- # `len(start_open)` key columns exactly match `start_open`.
+ "endOpen": [ # If the end is open, then the range excludes rows whose first
+ # `len(end_open)` key columns exactly match `end_open`.
"",
],
"startClosed": [ # If the start is closed, then the range includes all rows whose
@@ -6372,9 +7099,6 @@
],
},
],
- "all": True or False, # For convenience `all` can be set to `true` to indicate that this
- # `KeySet` matches all keys in the table or index. Note that any keys
- # specified in `keys` or `ranges` are only yielded once.
"keys": [ # A list of specific keys. Entries in `keys` should have exactly as
# many elements as there are columns in the primary or index key
# with which this `KeySet` is used. Individual key values are
@@ -6383,731 +7107,13 @@
"",
],
],
+ "all": True or False, # For convenience `all` can be set to `true` to indicate that this
+ # `KeySet` matches all keys in the table or index. Note that any keys
+ # specified in `keys` or `ranges` are only yielded once.
},
- "columns": [ # Required. The columns of table to be returned for each row matching
- # this request.
- "A String",
- ],
- "transaction": { # This message is used to select the transaction in which a # The transaction to use. If none is provided, the default is a
- # temporary read-only transaction with strong concurrency.
- # Read or
- # ExecuteSql call runs.
- #
- # See TransactionOptions for more information about transactions.
- "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
- # This is the most efficient way to execute a transaction that
- # consists of a single SQL query.
- #
- #
- # Each session can have at most one active transaction at a time. After the
- # active transaction is completed, the session can immediately be
- # re-used for the next transaction. It is not necessary to create a
- # new session for each transaction.
- #
- # # Transaction Modes
- #
- # Cloud Spanner supports three transaction modes:
- #
- # 1. Locking read-write. This type of transaction is the only way
- # to write data into Cloud Spanner. These transactions rely on
- # pessimistic locking and, if necessary, two-phase commit.
- # Locking read-write transactions may abort, requiring the
- # application to retry.
- #
- # 2. Snapshot read-only. 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. Snapshot read-only
- # transactions do not need to be committed.
- #
- # 3. Partitioned DML. This type of transaction is used to execute
- # a single Partitioned DML statement. Partitioned DML partitions
- # the key space and runs the DML statement over each partition
- # in parallel using separate, internal transactions that commit
- # independently. Partitioned DML transactions do not need to be
- # committed.
- #
- # For transactions that only read, snapshot read-only transactions
- # provide simpler semantics and are almost always faster. In
- # particular, read-only transactions do not take locks, so they do
- # not conflict with read-write transactions. As a consequence of not
- # taking locks, they also do not abort, so retry loops are not needed.
- #
- # Transactions may only read/write data in a single database. They
- # may, however, read/write data in different tables within that
- # database.
- #
- # ## Locking Read-Write Transactions
- #
- # Locking transactions may be used to atomically read-modify-write
- # data anywhere in a database. This type of transaction is externally
- # consistent.
- #
- # Clients should attempt to minimize the amount of time a transaction
- # is active. Faster transactions commit with higher probability
- # and cause less contention. Cloud Spanner attempts to keep read locks
- # active as long as the transaction continues to do reads, and the
- # transaction has not been terminated by
- # Commit or
- # Rollback. Long periods of
- # inactivity at the client may cause Cloud Spanner to release a
- # transaction's locks and abort it.
- #
- # Conceptually, a read-write transaction consists of zero or more
- # reads or SQL statements followed by
- # Commit. At any time before
- # Commit, the client can send a
- # Rollback request to abort the
- # transaction.
- #
- # ### Semantics
- #
- # Cloud Spanner can commit the transaction if all read locks it acquired
- # are still valid at commit time, and it is able to acquire write
- # locks for all writes. Cloud Spanner can abort the transaction for any
- # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
- # that the transaction has not modified any user data in Cloud Spanner.
- #
- # Unless the transaction commits, Cloud Spanner makes no guarantees about
- # how long the transaction's locks were held for. It is an error to
- # use Cloud Spanner locks for any sort of mutual exclusion other than
- # between Cloud Spanner transactions themselves.
- #
- # ### Retrying Aborted Transactions
- #
- # When a transaction aborts, the application can choose to retry the
- # whole transaction again. To maximize the chances of successfully
- # committing the retry, the client should execute the retry in the
- # same session as the original attempt. The original session's lock
- # priority increases with each consecutive abort, meaning that each
- # attempt has a slightly better chance of success than the previous.
- #
- # Under some circumstances (e.g., many transactions attempting to
- # modify the same row(s)), a transaction can abort many times in a
- # short period before successfully committing. Thus, it is not a good
- # idea to cap the number of retries a transaction can attempt;
- # instead, it is better to limit the total amount of wall time spent
- # retrying.
- #
- # ### Idle Transactions
- #
- # A transaction is considered idle if it has no outstanding reads or
- # SQL queries and has not started a read or SQL query within the last 10
- # seconds. Idle transactions can be aborted by Cloud Spanner so that they
- # don't hold on to locks indefinitely. In that case, the commit will
- # fail with error `ABORTED`.
- #
- # If this behavior is undesirable, periodically executing a simple
- # SQL query in the transaction (e.g., `SELECT 1`) prevents the
- # transaction from becoming idle.
- #
- # ## Snapshot Read-Only Transactions
- #
- # Snapshot read-only transactions provides a simpler method than
- # locking read-write transactions for doing several consistent
- # reads. However, this type of transaction does not support writes.
- #
- # Snapshot transactions do not take locks. Instead, they work by
- # choosing a Cloud Spanner timestamp, then executing all reads at that
- # timestamp. Since they do not acquire locks, they do not block
- # concurrent read-write transactions.
- #
- # Unlike locking read-write transactions, snapshot read-only
- # transactions never abort. They can fail if the chosen read
- # timestamp is garbage collected; however, the default garbage
- # collection policy is generous enough that most applications do not
- # need to worry about this in practice.
- #
- # Snapshot read-only transactions do not need to call
- # Commit or
- # Rollback (and in fact are not
- # permitted to do so).
- #
- # To execute a snapshot transaction, the client specifies a timestamp
- # bound, which tells Cloud Spanner how to choose a read timestamp.
- #
- # The types of timestamp bound are:
- #
- # - Strong (the default).
- # - Bounded staleness.
- # - Exact staleness.
- #
- # If the Cloud Spanner database to be read is geographically distributed,
- # stale read-only transactions can execute more quickly than strong
- # or read-write transaction, because they are able to execute far
- # from the leader replica.
- #
- # Each type of timestamp bound is discussed in detail below.
- #
- # ### Strong
- #
- # Strong reads are guaranteed to see the effects of all transactions
- # that have committed before the start of the read. Furthermore, all
- # rows yielded by a single read are consistent with each other -- if
- # any part of the read observes a transaction, all parts of the read
- # see the transaction.
- #
- # Strong reads are not repeatable: two consecutive strong read-only
- # transactions might return inconsistent results if there are
- # concurrent writes. If consistency across reads is required, the
- # reads should be executed within a transaction or at an exact read
- # timestamp.
- #
- # See TransactionOptions.ReadOnly.strong.
- #
- # ### Exact Staleness
- #
- # These timestamp bounds execute reads at a user-specified
- # timestamp. Reads at a timestamp are guaranteed to see a consistent
- # prefix of the global transaction history: they observe
- # modifications done by all transactions with a commit timestamp <=
- # the read timestamp, and observe none of the modifications done by
- # transactions with a larger commit timestamp. They will block until
- # all conflicting transactions that may be assigned commit timestamps
- # <= the read timestamp have finished.
- #
- # The timestamp can either be expressed as an absolute Cloud Spanner commit
- # timestamp or a staleness relative to the current time.
- #
- # These modes do not require a "negotiation phase" to pick a
- # timestamp. As a result, they execute slightly faster than the
- # equivalent boundedly stale concurrency modes. On the other hand,
- # boundedly stale reads usually return fresher results.
- #
- # See TransactionOptions.ReadOnly.read_timestamp and
- # TransactionOptions.ReadOnly.exact_staleness.
- #
- # ### Bounded Staleness
- #
- # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
- # subject to a user-provided staleness bound. Cloud Spanner chooses the
- # newest timestamp within the staleness bound that allows execution
- # of the reads at the closest available replica without blocking.
- #
- # All rows yielded are consistent with each other -- if any part of
- # the read observes a transaction, all parts of the read see the
- # transaction. Boundedly stale reads are not repeatable: two stale
- # reads, even if they use the same staleness bound, can execute at
- # different timestamps and thus return inconsistent results.
- #
- # Boundedly stale reads execute in two phases: the first phase
- # negotiates a timestamp among all replicas needed to serve the
- # read. In the second phase, reads are executed at the negotiated
- # timestamp.
- #
- # As a result of the two phase execution, bounded staleness reads are
- # usually a little slower than comparable exact staleness
- # reads. However, they are typically able to return fresher
- # results, and are more likely to execute at the closest replica.
- #
- # Because the timestamp negotiation requires up-front knowledge of
- # which rows will be read, it can only be used with single-use
- # read-only transactions.
- #
- # See TransactionOptions.ReadOnly.max_staleness and
- # TransactionOptions.ReadOnly.min_read_timestamp.
- #
- # ### Old Read Timestamps and Garbage Collection
- #
- # Cloud Spanner continuously garbage collects deleted and overwritten data
- # in the background to reclaim storage space. This process is known
- # as "version GC". By default, version GC reclaims versions after they
- # are one hour old. Because of this, Cloud Spanner cannot perform reads
- # at read timestamps more than one hour in the past. This
- # restriction also applies to in-progress reads and/or SQL queries whose
- # timestamp become too old while executing. Reads and SQL queries with
- # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
- #
- # ## Partitioned DML Transactions
- #
- # Partitioned DML transactions are used to execute DML statements with a
- # different execution strategy that provides different, and often better,
- # scalability properties for large, table-wide operations than DML in a
- # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
- # should prefer using ReadWrite transactions.
- #
- # Partitioned DML partitions the keyspace and runs the DML statement on each
- # partition in separate, internal transactions. These transactions commit
- # automatically when complete, and run independently from one another.
- #
- # To reduce lock contention, this execution strategy only acquires read locks
- # on rows that match the WHERE clause of the statement. Additionally, the
- # smaller per-partition transactions hold locks for less time.
- #
- # That said, Partitioned DML is not a drop-in replacement for standard DML used
- # in ReadWrite transactions.
- #
- # - The DML statement must be fully-partitionable. Specifically, the statement
- # must be expressible as the union of many statements which each access only
- # a single row of the table.
- #
- # - The statement is not applied atomically to all rows of the table. Rather,
- # the statement is applied atomically to partitions of the table, in
- # independent transactions. Secondary index rows are updated atomically
- # with the base table rows.
- #
- # - Partitioned DML does not guarantee exactly-once execution semantics
- # against a partition. The statement will be applied at least once to each
- # partition. It is strongly recommended that the DML statement should be
- # idempotent to avoid unexpected results. For instance, it is potentially
- # dangerous to run a statement such as
- # `UPDATE table SET column = column + 1` as it could be run multiple times
- # against some rows.
- #
- # - The partitions are committed automatically - there is no support for
- # Commit or Rollback. If the call returns an error, or if the client issuing
- # the ExecuteSql call dies, it is possible that some rows had the statement
- # executed on them successfully. It is also possible that statement was
- # never executed against other rows.
- #
- # - Partitioned DML transactions may only contain the execution of a single
- # DML statement via ExecuteSql or ExecuteStreamingSql.
- #
- # - If any error is encountered during the execution of the partitioned DML
- # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
- # value that cannot be stored due to schema constraints), then the
- # operation is stopped at that point and an error is returned. It is
- # possible that at this point, some partitions have been committed (or even
- # committed multiple times), and other partitions have not been run at all.
- #
- # Given the above, Partitioned DML is good fit for large, database-wide,
- # operations that are idempotent, such as deleting old rows from a very large
- # table.
- "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
- #
- # Authorization to begin a Partitioned DML transaction requires
- # `spanner.databases.beginPartitionedDmlTransaction` permission
- # on the `session` resource.
- },
- "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
- #
- # Authorization to begin a read-only transaction requires
- # `spanner.databases.beginReadOnlyTransaction` permission
- # on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
- # seconds. Guarantees that all writes that have committed more
- # than the specified number of seconds ago are visible. Because
- # Cloud Spanner chooses the exact timestamp, this mode works even if
- # the client's local clock is substantially skewed from Cloud Spanner
- # commit timestamps.
- #
- # Useful for reading the freshest data available at a nearby
- # replica, while bounding the possible staleness if the local
- # replica has fallen behind.
- #
- # Note that this option can only be used in single-use
- # transactions.
- "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
- # the Transaction message that describes the transaction.
- "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
- # old. The timestamp is chosen soon after the read is started.
- #
- # Guarantees that all writes that have committed more than the
- # specified number of seconds ago are visible. Because Cloud Spanner
- # chooses the exact timestamp, this mode works even if the client's
- # local clock is substantially skewed from Cloud Spanner commit
- # timestamps.
- #
- # Useful for reading at nearby replicas without the distributed
- # timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
- },
- "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
- #
- # Authorization to begin a read-write transaction requires
- # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
- # on the `session` resource.
- # transaction type has no options.
- },
- },
- "begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in
- # it. The transaction ID of the new transaction is returned in
- # ResultSetMetadata.transaction, which is a Transaction.
- #
- #
- # Each session can have at most one active transaction at a time. After the
- # active transaction is completed, the session can immediately be
- # re-used for the next transaction. It is not necessary to create a
- # new session for each transaction.
- #
- # # Transaction Modes
- #
- # Cloud Spanner supports three transaction modes:
- #
- # 1. Locking read-write. This type of transaction is the only way
- # to write data into Cloud Spanner. These transactions rely on
- # pessimistic locking and, if necessary, two-phase commit.
- # Locking read-write transactions may abort, requiring the
- # application to retry.
- #
- # 2. Snapshot read-only. 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. Snapshot read-only
- # transactions do not need to be committed.
- #
- # 3. Partitioned DML. This type of transaction is used to execute
- # a single Partitioned DML statement. Partitioned DML partitions
- # the key space and runs the DML statement over each partition
- # in parallel using separate, internal transactions that commit
- # independently. Partitioned DML transactions do not need to be
- # committed.
- #
- # For transactions that only read, snapshot read-only transactions
- # provide simpler semantics and are almost always faster. In
- # particular, read-only transactions do not take locks, so they do
- # not conflict with read-write transactions. As a consequence of not
- # taking locks, they also do not abort, so retry loops are not needed.
- #
- # Transactions may only read/write data in a single database. They
- # may, however, read/write data in different tables within that
- # database.
- #
- # ## Locking Read-Write Transactions
- #
- # Locking transactions may be used to atomically read-modify-write
- # data anywhere in a database. This type of transaction is externally
- # consistent.
- #
- # Clients should attempt to minimize the amount of time a transaction
- # is active. Faster transactions commit with higher probability
- # and cause less contention. Cloud Spanner attempts to keep read locks
- # active as long as the transaction continues to do reads, and the
- # transaction has not been terminated by
- # Commit or
- # Rollback. Long periods of
- # inactivity at the client may cause Cloud Spanner to release a
- # transaction's locks and abort it.
- #
- # Conceptually, a read-write transaction consists of zero or more
- # reads or SQL statements followed by
- # Commit. At any time before
- # Commit, the client can send a
- # Rollback request to abort the
- # transaction.
- #
- # ### Semantics
- #
- # Cloud Spanner can commit the transaction if all read locks it acquired
- # are still valid at commit time, and it is able to acquire write
- # locks for all writes. Cloud Spanner can abort the transaction for any
- # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
- # that the transaction has not modified any user data in Cloud Spanner.
- #
- # Unless the transaction commits, Cloud Spanner makes no guarantees about
- # how long the transaction's locks were held for. It is an error to
- # use Cloud Spanner locks for any sort of mutual exclusion other than
- # between Cloud Spanner transactions themselves.
- #
- # ### Retrying Aborted Transactions
- #
- # When a transaction aborts, the application can choose to retry the
- # whole transaction again. To maximize the chances of successfully
- # committing the retry, the client should execute the retry in the
- # same session as the original attempt. The original session's lock
- # priority increases with each consecutive abort, meaning that each
- # attempt has a slightly better chance of success than the previous.
- #
- # Under some circumstances (e.g., many transactions attempting to
- # modify the same row(s)), a transaction can abort many times in a
- # short period before successfully committing. Thus, it is not a good
- # idea to cap the number of retries a transaction can attempt;
- # instead, it is better to limit the total amount of wall time spent
- # retrying.
- #
- # ### Idle Transactions
- #
- # A transaction is considered idle if it has no outstanding reads or
- # SQL queries and has not started a read or SQL query within the last 10
- # seconds. Idle transactions can be aborted by Cloud Spanner so that they
- # don't hold on to locks indefinitely. In that case, the commit will
- # fail with error `ABORTED`.
- #
- # If this behavior is undesirable, periodically executing a simple
- # SQL query in the transaction (e.g., `SELECT 1`) prevents the
- # transaction from becoming idle.
- #
- # ## Snapshot Read-Only Transactions
- #
- # Snapshot read-only transactions provides a simpler method than
- # locking read-write transactions for doing several consistent
- # reads. However, this type of transaction does not support writes.
- #
- # Snapshot transactions do not take locks. Instead, they work by
- # choosing a Cloud Spanner timestamp, then executing all reads at that
- # timestamp. Since they do not acquire locks, they do not block
- # concurrent read-write transactions.
- #
- # Unlike locking read-write transactions, snapshot read-only
- # transactions never abort. They can fail if the chosen read
- # timestamp is garbage collected; however, the default garbage
- # collection policy is generous enough that most applications do not
- # need to worry about this in practice.
- #
- # Snapshot read-only transactions do not need to call
- # Commit or
- # Rollback (and in fact are not
- # permitted to do so).
- #
- # To execute a snapshot transaction, the client specifies a timestamp
- # bound, which tells Cloud Spanner how to choose a read timestamp.
- #
- # The types of timestamp bound are:
- #
- # - Strong (the default).
- # - Bounded staleness.
- # - Exact staleness.
- #
- # If the Cloud Spanner database to be read is geographically distributed,
- # stale read-only transactions can execute more quickly than strong
- # or read-write transaction, because they are able to execute far
- # from the leader replica.
- #
- # Each type of timestamp bound is discussed in detail below.
- #
- # ### Strong
- #
- # Strong reads are guaranteed to see the effects of all transactions
- # that have committed before the start of the read. Furthermore, all
- # rows yielded by a single read are consistent with each other -- if
- # any part of the read observes a transaction, all parts of the read
- # see the transaction.
- #
- # Strong reads are not repeatable: two consecutive strong read-only
- # transactions might return inconsistent results if there are
- # concurrent writes. If consistency across reads is required, the
- # reads should be executed within a transaction or at an exact read
- # timestamp.
- #
- # See TransactionOptions.ReadOnly.strong.
- #
- # ### Exact Staleness
- #
- # These timestamp bounds execute reads at a user-specified
- # timestamp. Reads at a timestamp are guaranteed to see a consistent
- # prefix of the global transaction history: they observe
- # modifications done by all transactions with a commit timestamp <=
- # the read timestamp, and observe none of the modifications done by
- # transactions with a larger commit timestamp. They will block until
- # all conflicting transactions that may be assigned commit timestamps
- # <= the read timestamp have finished.
- #
- # The timestamp can either be expressed as an absolute Cloud Spanner commit
- # timestamp or a staleness relative to the current time.
- #
- # These modes do not require a "negotiation phase" to pick a
- # timestamp. As a result, they execute slightly faster than the
- # equivalent boundedly stale concurrency modes. On the other hand,
- # boundedly stale reads usually return fresher results.
- #
- # See TransactionOptions.ReadOnly.read_timestamp and
- # TransactionOptions.ReadOnly.exact_staleness.
- #
- # ### Bounded Staleness
- #
- # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
- # subject to a user-provided staleness bound. Cloud Spanner chooses the
- # newest timestamp within the staleness bound that allows execution
- # of the reads at the closest available replica without blocking.
- #
- # All rows yielded are consistent with each other -- if any part of
- # the read observes a transaction, all parts of the read see the
- # transaction. Boundedly stale reads are not repeatable: two stale
- # reads, even if they use the same staleness bound, can execute at
- # different timestamps and thus return inconsistent results.
- #
- # Boundedly stale reads execute in two phases: the first phase
- # negotiates a timestamp among all replicas needed to serve the
- # read. In the second phase, reads are executed at the negotiated
- # timestamp.
- #
- # As a result of the two phase execution, bounded staleness reads are
- # usually a little slower than comparable exact staleness
- # reads. However, they are typically able to return fresher
- # results, and are more likely to execute at the closest replica.
- #
- # Because the timestamp negotiation requires up-front knowledge of
- # which rows will be read, it can only be used with single-use
- # read-only transactions.
- #
- # See TransactionOptions.ReadOnly.max_staleness and
- # TransactionOptions.ReadOnly.min_read_timestamp.
- #
- # ### Old Read Timestamps and Garbage Collection
- #
- # Cloud Spanner continuously garbage collects deleted and overwritten data
- # in the background to reclaim storage space. This process is known
- # as "version GC". By default, version GC reclaims versions after they
- # are one hour old. Because of this, Cloud Spanner cannot perform reads
- # at read timestamps more than one hour in the past. This
- # restriction also applies to in-progress reads and/or SQL queries whose
- # timestamp become too old while executing. Reads and SQL queries with
- # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
- #
- # ## Partitioned DML Transactions
- #
- # Partitioned DML transactions are used to execute DML statements with a
- # different execution strategy that provides different, and often better,
- # scalability properties for large, table-wide operations than DML in a
- # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
- # should prefer using ReadWrite transactions.
- #
- # Partitioned DML partitions the keyspace and runs the DML statement on each
- # partition in separate, internal transactions. These transactions commit
- # automatically when complete, and run independently from one another.
- #
- # To reduce lock contention, this execution strategy only acquires read locks
- # on rows that match the WHERE clause of the statement. Additionally, the
- # smaller per-partition transactions hold locks for less time.
- #
- # That said, Partitioned DML is not a drop-in replacement for standard DML used
- # in ReadWrite transactions.
- #
- # - The DML statement must be fully-partitionable. Specifically, the statement
- # must be expressible as the union of many statements which each access only
- # a single row of the table.
- #
- # - The statement is not applied atomically to all rows of the table. Rather,
- # the statement is applied atomically to partitions of the table, in
- # independent transactions. Secondary index rows are updated atomically
- # with the base table rows.
- #
- # - Partitioned DML does not guarantee exactly-once execution semantics
- # against a partition. The statement will be applied at least once to each
- # partition. It is strongly recommended that the DML statement should be
- # idempotent to avoid unexpected results. For instance, it is potentially
- # dangerous to run a statement such as
- # `UPDATE table SET column = column + 1` as it could be run multiple times
- # against some rows.
- #
- # - The partitions are committed automatically - there is no support for
- # Commit or Rollback. If the call returns an error, or if the client issuing
- # the ExecuteSql call dies, it is possible that some rows had the statement
- # executed on them successfully. It is also possible that statement was
- # never executed against other rows.
- #
- # - Partitioned DML transactions may only contain the execution of a single
- # DML statement via ExecuteSql or ExecuteStreamingSql.
- #
- # - If any error is encountered during the execution of the partitioned DML
- # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
- # value that cannot be stored due to schema constraints), then the
- # operation is stopped at that point and an error is returned. It is
- # possible that at this point, some partitions have been committed (or even
- # committed multiple times), and other partitions have not been run at all.
- #
- # Given the above, Partitioned DML is good fit for large, database-wide,
- # operations that are idempotent, such as deleting old rows from a very large
- # table.
- "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
- #
- # Authorization to begin a Partitioned DML transaction requires
- # `spanner.databases.beginPartitionedDmlTransaction` permission
- # on the `session` resource.
- },
- "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
- #
- # Authorization to begin a read-only transaction requires
- # `spanner.databases.beginReadOnlyTransaction` permission
- # on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
- # seconds. Guarantees that all writes that have committed more
- # than the specified number of seconds ago are visible. Because
- # Cloud Spanner chooses the exact timestamp, this mode works even if
- # the client's local clock is substantially skewed from Cloud Spanner
- # commit timestamps.
- #
- # Useful for reading the freshest data available at a nearby
- # replica, while bounding the possible staleness if the local
- # replica has fallen behind.
- #
- # Note that this option can only be used in single-use
- # transactions.
- "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
- # the Transaction message that describes the transaction.
- "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
- # old. The timestamp is chosen soon after the read is started.
- #
- # Guarantees that all writes that have committed more than the
- # specified number of seconds ago are visible. Because Cloud Spanner
- # chooses the exact timestamp, this mode works even if the client's
- # local clock is substantially skewed from Cloud Spanner commit
- # timestamps.
- #
- # Useful for reading at nearby replicas without the distributed
- # timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
- },
- "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
- #
- # Authorization to begin a read-write transaction requires
- # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
- # on the `session` resource.
- # transaction type has no options.
- },
- },
- "id": "A String", # Execute the read or SQL query in a previously-started transaction.
- },
- "resumeToken": "A String", # If this request is resuming a previously interrupted read,
- # `resume_token` should be copied from the last
- # PartialResultSet yielded before the interruption. Doing this
- # enables the new read to resume where the last read left off. The
- # rest of the request parameters must exactly match the request
- # that yielded this token.
- "partitionToken": "A String", # If present, results will be restricted to the specified partition
- # previously created using PartitionRead(). There must be an exact
- # match for the values of fields common to this message and the
- # PartitionReadRequest message used to create this partition_token.
- "table": "A String", # Required. The name of the table in the database to be read.
- "limit": "A String", # If greater than zero, only the first `limit` rows are yielded. If `limit`
- # is zero, the default is no limit. A limit cannot be specified if
- # `partition_token` is set.
+ "index": "A String", # If non-empty, the name of an index on table. This index is
+ # used instead of the table primary key when interpreting key_set
+ # and sorting result rows. See key_set for further information.
}
x__xgafv: string, V1 error format.
@@ -7120,99 +7126,6 @@
{ # Results from Read or
# ExecuteSql.
- "stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the SQL statement that
- # produced this result set. These can be requested by setting
- # ExecuteSqlRequest.query_mode.
- # DML statements always produce stats containing the number of rows
- # modified, unless executed using the
- # ExecuteSqlRequest.QueryMode.PLAN ExecuteSqlRequest.query_mode.
- # Other fields may or may not be populated, based on the
- # ExecuteSqlRequest.query_mode.
- "rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.
- "queryStats": { # Aggregated statistics from the execution of the query. Only present when
- # the query is profiled. For example, a query could return the statistics as
- # follows:
- #
- # {
- # "rows_returned": "3",
- # "elapsed_time": "1.22 secs",
- # "cpu_time": "1.19 secs"
- # }
- "a_key": "", # Properties of the object.
- },
- "rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it
- # returns a lower bound of the rows modified.
- "queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
- "planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
- # with the plan root. Each PlanNode's `id` corresponds to its index in
- # `plan_nodes`.
- { # Node information for nodes appearing in a QueryPlan.plan_nodes.
- "metadata": { # Attributes relevant to the node contained in a group of key-value pairs.
- # For example, a Parameter Reference node could have the following
- # information in its metadata:
- #
- # {
- # "parameter_reference": "param1",
- # "parameter_type": "array"
- # }
- "a_key": "", # Properties of the object.
- },
- "executionStats": { # The execution statistics associated with the node, contained in a group of
- # key-value pairs. Only present if the plan was returned as a result of a
- # profile query. For example, number of executions, number of rows/time per
- # execution etc.
- "a_key": "", # Properties of the object.
- },
- "shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
- # `SCALAR` PlanNode(s).
- "description": "A String", # A string representation of the expression subtree rooted at this node.
- "subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases
- # where the `description` string of this node references a `SCALAR`
- # subquery contained in the expression subtree rooted at this node. The
- # referenced `SCALAR` subquery may not necessarily be a direct child of
- # this node.
- "a_key": 42,
- },
- },
- "index": 42, # The `PlanNode`'s index in node list.
- "kind": "A String", # Used to determine the type of node. May be needed for visualizing
- # different kinds of nodes differently. For example, If the node is a
- # SCALAR node, it will have a condensed representation
- # which can be used to directly embed a description of the node in its
- # parent.
- "displayName": "A String", # The display name for the node.
- "childLinks": [ # List of child node `index`es and their relationship to this parent.
- { # Metadata associated with a parent-child relationship appearing in a
- # PlanNode.
- "variable": "A String", # Only present if the child node is SCALAR and corresponds
- # to an output variable of the parent node. The field carries the name of
- # the output variable.
- # For example, a `TableScan` operator that reads rows from a table will
- # have child links to the `SCALAR` nodes representing the output variables
- # created for each column that is read by the operator. The corresponding
- # `variable` fields will be set to the variable names assigned to the
- # columns.
- "childIndex": 42, # The node to which the link points.
- "type": "A String", # The type of the link. For example, in Hash Joins this could be used to
- # distinguish between the build child and the probe child, or in the case
- # of the child being an output variable, to represent the tag associated
- # with the output variable.
- },
- ],
- },
- ],
- },
- },
- "rows": [ # Each element in `rows` is a row whose format is defined by
- # metadata.row_type. The ith element
- # in each row matches the ith field in
- # metadata.row_type. Elements are
- # encoded based on type as described
- # here.
- [
- "",
- ],
- ],
"metadata": { # Metadata about a ResultSet or PartialResultSet. # Metadata about the result set, such as row type information.
"rowType": { # `StructType` defines the fields of a STRUCT type. # Indicates the field names and types for the rows in the result
# set. For example, a SQL query like `"SELECT UserId, UserName FROM
@@ -7242,6 +7155,12 @@
},
"transaction": { # A transaction. # If the read or SQL query began a transaction as a side-effect, the
# information about the new transaction is yielded here.
+ "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
+ # for the transaction. Not returned by default: see
+ # TransactionOptions.ReadOnly.return_read_timestamp.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
"id": "A String", # `id` may be used to identify the transaction in subsequent
# Read,
# ExecuteSql,
@@ -7250,14 +7169,101 @@
#
# Single-use read-only transactions do not have IDs, because
# single-use transactions do not support multiple requests.
- "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
- # for the transaction. Not returned by default: see
- # TransactionOptions.ReadOnly.return_read_timestamp.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
},
},
+ "stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the SQL statement that
+ # produced this result set. These can be requested by setting
+ # ExecuteSqlRequest.query_mode.
+ # DML statements always produce stats containing the number of rows
+ # modified, unless executed using the
+ # ExecuteSqlRequest.QueryMode.PLAN ExecuteSqlRequest.query_mode.
+ # Other fields may or may not be populated, based on the
+ # ExecuteSqlRequest.query_mode.
+ "rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it
+ # returns a lower bound of the rows modified.
+ "queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
+ "planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
+ # with the plan root. Each PlanNode's `id` corresponds to its index in
+ # `plan_nodes`.
+ { # Node information for nodes appearing in a QueryPlan.plan_nodes.
+ "displayName": "A String", # The display name for the node.
+ "executionStats": { # The execution statistics associated with the node, contained in a group of
+ # key-value pairs. Only present if the plan was returned as a result of a
+ # profile query. For example, number of executions, number of rows/time per
+ # execution etc.
+ "a_key": "", # Properties of the object.
+ },
+ "shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
+ # `SCALAR` PlanNode(s).
+ "subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases
+ # where the `description` string of this node references a `SCALAR`
+ # subquery contained in the expression subtree rooted at this node. The
+ # referenced `SCALAR` subquery may not necessarily be a direct child of
+ # this node.
+ "a_key": 42,
+ },
+ "description": "A String", # A string representation of the expression subtree rooted at this node.
+ },
+ "metadata": { # Attributes relevant to the node contained in a group of key-value pairs.
+ # For example, a Parameter Reference node could have the following
+ # information in its metadata:
+ #
+ # {
+ # "parameter_reference": "param1",
+ # "parameter_type": "array"
+ # }
+ "a_key": "", # Properties of the object.
+ },
+ "childLinks": [ # List of child node `index`es and their relationship to this parent.
+ { # Metadata associated with a parent-child relationship appearing in a
+ # PlanNode.
+ "type": "A String", # The type of the link. For example, in Hash Joins this could be used to
+ # distinguish between the build child and the probe child, or in the case
+ # of the child being an output variable, to represent the tag associated
+ # with the output variable.
+ "variable": "A String", # Only present if the child node is SCALAR and corresponds
+ # to an output variable of the parent node. The field carries the name of
+ # the output variable.
+ # For example, a `TableScan` operator that reads rows from a table will
+ # have child links to the `SCALAR` nodes representing the output variables
+ # created for each column that is read by the operator. The corresponding
+ # `variable` fields will be set to the variable names assigned to the
+ # columns.
+ "childIndex": 42, # The node to which the link points.
+ },
+ ],
+ "index": 42, # The `PlanNode`'s index in node list.
+ "kind": "A String", # Used to determine the type of node. May be needed for visualizing
+ # different kinds of nodes differently. For example, If the node is a
+ # SCALAR node, it will have a condensed representation
+ # which can be used to directly embed a description of the node in its
+ # parent.
+ },
+ ],
+ },
+ "rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.
+ "queryStats": { # Aggregated statistics from the execution of the query. Only present when
+ # the query is profiled. For example, a query could return the statistics as
+ # follows:
+ #
+ # {
+ # "rows_returned": "3",
+ # "elapsed_time": "1.22 secs",
+ # "cpu_time": "1.19 secs"
+ # }
+ "a_key": "", # Properties of the object.
+ },
+ },
+ "rows": [ # Each element in `rows` is a row whose format is defined by
+ # metadata.row_type. The ith element
+ # in each row matches the ith field in
+ # metadata.row_type. Elements are
+ # encoded based on type as described
+ # here.
+ [
+ "",
+ ],
+ ],
}</pre>
</div>
@@ -7316,505 +7322,13 @@
{ # The request for Read and
# StreamingRead.
- "index": "A String", # If non-empty, the name of an index on table. This index is
- # used instead of the table primary key when interpreting key_set
- # and sorting result rows. See key_set for further information.
- "keySet": { # `KeySet` defines a collection of Cloud Spanner keys and/or key ranges. All # Required. `key_set` identifies the rows to be yielded. `key_set` names the
- # primary keys of the rows in table to be yielded, unless index
- # is present. If index is present, then key_set instead names
- # index keys in index.
- #
- # If the partition_token field is empty, rows are yielded
- # in table primary key order (if index is empty) or index key order
- # (if index is non-empty). If the partition_token field is not
- # empty, rows will be yielded in an unspecified order.
- #
- # It is not an error for the `key_set` to name rows that do not
- # exist in the database. Read yields nothing for nonexistent rows.
- # the keys are expected to be in the same table or index. The keys need
- # not be sorted in any particular way.
- #
- # If the same key is specified multiple times in the set (for example
- # if two ranges, two keys, or a key and a range overlap), Cloud Spanner
- # behaves as if the key were only specified once.
- "ranges": [ # A list of key ranges. See KeyRange for more information about
- # key range specifications.
- { # KeyRange represents a range of rows in a table or index.
- #
- # A range has a start key and an end key. These keys can be open or
- # closed, indicating if the range includes rows with that key.
- #
- # Keys are represented by lists, where the ith value in the list
- # corresponds to the ith component of the table or index primary key.
- # Individual values are encoded as described
- # here.
- #
- # For example, consider the following table definition:
- #
- # CREATE TABLE UserEvents (
- # UserName STRING(MAX),
- # EventDate STRING(10)
- # ) PRIMARY KEY(UserName, EventDate);
- #
- # The following keys name rows in this table:
- #
- # "Bob", "2014-09-23"
- #
- # Since the `UserEvents` table's `PRIMARY KEY` clause names two
- # columns, each `UserEvents` key has two elements; the first is the
- # `UserName`, and the second is the `EventDate`.
- #
- # Key ranges with multiple components are interpreted
- # lexicographically by component using the table or index key's declared
- # sort order. For example, the following range returns all events for
- # user `"Bob"` that occurred in the year 2015:
- #
- # "start_closed": ["Bob", "2015-01-01"]
- # "end_closed": ["Bob", "2015-12-31"]
- #
- # Start and end keys can omit trailing key components. This affects the
- # inclusion and exclusion of rows that exactly match the provided key
- # components: if the key is closed, then rows that exactly match the
- # provided components are included; if the key is open, then rows
- # that exactly match are not included.
- #
- # For example, the following range includes all events for `"Bob"` that
- # occurred during and after the year 2000:
- #
- # "start_closed": ["Bob", "2000-01-01"]
- # "end_closed": ["Bob"]
- #
- # The next example retrieves all events for `"Bob"`:
- #
- # "start_closed": ["Bob"]
- # "end_closed": ["Bob"]
- #
- # To retrieve events before the year 2000:
- #
- # "start_closed": ["Bob"]
- # "end_open": ["Bob", "2000-01-01"]
- #
- # The following range includes all rows in the table:
- #
- # "start_closed": []
- # "end_closed": []
- #
- # This range returns all users whose `UserName` begins with any
- # character from A to C:
- #
- # "start_closed": ["A"]
- # "end_open": ["D"]
- #
- # This range returns all users whose `UserName` begins with B:
- #
- # "start_closed": ["B"]
- # "end_open": ["C"]
- #
- # Key ranges honor column sort order. For example, suppose a table is
- # defined as follows:
- #
- # CREATE TABLE DescendingSortedTable {
- # Key INT64,
- # ...
- # ) PRIMARY KEY(Key DESC);
- #
- # The following range retrieves all rows with key values between 1
- # and 100 inclusive:
- #
- # "start_closed": ["100"]
- # "end_closed": ["1"]
- #
- # Note that 100 is passed as the start, and 1 is passed as the end,
- # because `Key` is a descending column in the schema.
- "endOpen": [ # If the end is open, then the range excludes rows whose first
- # `len(end_open)` key columns exactly match `end_open`.
- "",
- ],
- "endClosed": [ # If the end is closed, then the range includes all rows whose
- # first `len(end_closed)` key columns exactly match `end_closed`.
- "",
- ],
- "startOpen": [ # If the start is open, then the range excludes rows whose first
- # `len(start_open)` key columns exactly match `start_open`.
- "",
- ],
- "startClosed": [ # If the start is closed, then the range includes all rows whose
- # first `len(start_closed)` key columns exactly match `start_closed`.
- "",
- ],
- },
- ],
- "all": True or False, # For convenience `all` can be set to `true` to indicate that this
- # `KeySet` matches all keys in the table or index. Note that any keys
- # specified in `keys` or `ranges` are only yielded once.
- "keys": [ # A list of specific keys. Entries in `keys` should have exactly as
- # many elements as there are columns in the primary or index key
- # with which this `KeySet` is used. Individual key values are
- # encoded as described here.
- [
- "",
- ],
- ],
- },
- "columns": [ # Required. The columns of table to be returned for each row matching
- # this request.
- "A String",
- ],
"transaction": { # This message is used to select the transaction in which a # The transaction to use. If none is provided, the default is a
# temporary read-only transaction with strong concurrency.
# Read or
# ExecuteSql call runs.
#
# See TransactionOptions for more information about transactions.
- "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
- # This is the most efficient way to execute a transaction that
- # consists of a single SQL query.
- #
- #
- # Each session can have at most one active transaction at a time. After the
- # active transaction is completed, the session can immediately be
- # re-used for the next transaction. It is not necessary to create a
- # new session for each transaction.
- #
- # # Transaction Modes
- #
- # Cloud Spanner supports three transaction modes:
- #
- # 1. Locking read-write. This type of transaction is the only way
- # to write data into Cloud Spanner. These transactions rely on
- # pessimistic locking and, if necessary, two-phase commit.
- # Locking read-write transactions may abort, requiring the
- # application to retry.
- #
- # 2. Snapshot read-only. 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. Snapshot read-only
- # transactions do not need to be committed.
- #
- # 3. Partitioned DML. This type of transaction is used to execute
- # a single Partitioned DML statement. Partitioned DML partitions
- # the key space and runs the DML statement over each partition
- # in parallel using separate, internal transactions that commit
- # independently. Partitioned DML transactions do not need to be
- # committed.
- #
- # For transactions that only read, snapshot read-only transactions
- # provide simpler semantics and are almost always faster. In
- # particular, read-only transactions do not take locks, so they do
- # not conflict with read-write transactions. As a consequence of not
- # taking locks, they also do not abort, so retry loops are not needed.
- #
- # Transactions may only read/write data in a single database. They
- # may, however, read/write data in different tables within that
- # database.
- #
- # ## Locking Read-Write Transactions
- #
- # Locking transactions may be used to atomically read-modify-write
- # data anywhere in a database. This type of transaction is externally
- # consistent.
- #
- # Clients should attempt to minimize the amount of time a transaction
- # is active. Faster transactions commit with higher probability
- # and cause less contention. Cloud Spanner attempts to keep read locks
- # active as long as the transaction continues to do reads, and the
- # transaction has not been terminated by
- # Commit or
- # Rollback. Long periods of
- # inactivity at the client may cause Cloud Spanner to release a
- # transaction's locks and abort it.
- #
- # Conceptually, a read-write transaction consists of zero or more
- # reads or SQL statements followed by
- # Commit. At any time before
- # Commit, the client can send a
- # Rollback request to abort the
- # transaction.
- #
- # ### Semantics
- #
- # Cloud Spanner can commit the transaction if all read locks it acquired
- # are still valid at commit time, and it is able to acquire write
- # locks for all writes. Cloud Spanner can abort the transaction for any
- # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
- # that the transaction has not modified any user data in Cloud Spanner.
- #
- # Unless the transaction commits, Cloud Spanner makes no guarantees about
- # how long the transaction's locks were held for. It is an error to
- # use Cloud Spanner locks for any sort of mutual exclusion other than
- # between Cloud Spanner transactions themselves.
- #
- # ### Retrying Aborted Transactions
- #
- # When a transaction aborts, the application can choose to retry the
- # whole transaction again. To maximize the chances of successfully
- # committing the retry, the client should execute the retry in the
- # same session as the original attempt. The original session's lock
- # priority increases with each consecutive abort, meaning that each
- # attempt has a slightly better chance of success than the previous.
- #
- # Under some circumstances (e.g., many transactions attempting to
- # modify the same row(s)), a transaction can abort many times in a
- # short period before successfully committing. Thus, it is not a good
- # idea to cap the number of retries a transaction can attempt;
- # instead, it is better to limit the total amount of wall time spent
- # retrying.
- #
- # ### Idle Transactions
- #
- # A transaction is considered idle if it has no outstanding reads or
- # SQL queries and has not started a read or SQL query within the last 10
- # seconds. Idle transactions can be aborted by Cloud Spanner so that they
- # don't hold on to locks indefinitely. In that case, the commit will
- # fail with error `ABORTED`.
- #
- # If this behavior is undesirable, periodically executing a simple
- # SQL query in the transaction (e.g., `SELECT 1`) prevents the
- # transaction from becoming idle.
- #
- # ## Snapshot Read-Only Transactions
- #
- # Snapshot read-only transactions provides a simpler method than
- # locking read-write transactions for doing several consistent
- # reads. However, this type of transaction does not support writes.
- #
- # Snapshot transactions do not take locks. Instead, they work by
- # choosing a Cloud Spanner timestamp, then executing all reads at that
- # timestamp. Since they do not acquire locks, they do not block
- # concurrent read-write transactions.
- #
- # Unlike locking read-write transactions, snapshot read-only
- # transactions never abort. They can fail if the chosen read
- # timestamp is garbage collected; however, the default garbage
- # collection policy is generous enough that most applications do not
- # need to worry about this in practice.
- #
- # Snapshot read-only transactions do not need to call
- # Commit or
- # Rollback (and in fact are not
- # permitted to do so).
- #
- # To execute a snapshot transaction, the client specifies a timestamp
- # bound, which tells Cloud Spanner how to choose a read timestamp.
- #
- # The types of timestamp bound are:
- #
- # - Strong (the default).
- # - Bounded staleness.
- # - Exact staleness.
- #
- # If the Cloud Spanner database to be read is geographically distributed,
- # stale read-only transactions can execute more quickly than strong
- # or read-write transaction, because they are able to execute far
- # from the leader replica.
- #
- # Each type of timestamp bound is discussed in detail below.
- #
- # ### Strong
- #
- # Strong reads are guaranteed to see the effects of all transactions
- # that have committed before the start of the read. Furthermore, all
- # rows yielded by a single read are consistent with each other -- if
- # any part of the read observes a transaction, all parts of the read
- # see the transaction.
- #
- # Strong reads are not repeatable: two consecutive strong read-only
- # transactions might return inconsistent results if there are
- # concurrent writes. If consistency across reads is required, the
- # reads should be executed within a transaction or at an exact read
- # timestamp.
- #
- # See TransactionOptions.ReadOnly.strong.
- #
- # ### Exact Staleness
- #
- # These timestamp bounds execute reads at a user-specified
- # timestamp. Reads at a timestamp are guaranteed to see a consistent
- # prefix of the global transaction history: they observe
- # modifications done by all transactions with a commit timestamp <=
- # the read timestamp, and observe none of the modifications done by
- # transactions with a larger commit timestamp. They will block until
- # all conflicting transactions that may be assigned commit timestamps
- # <= the read timestamp have finished.
- #
- # The timestamp can either be expressed as an absolute Cloud Spanner commit
- # timestamp or a staleness relative to the current time.
- #
- # These modes do not require a "negotiation phase" to pick a
- # timestamp. As a result, they execute slightly faster than the
- # equivalent boundedly stale concurrency modes. On the other hand,
- # boundedly stale reads usually return fresher results.
- #
- # See TransactionOptions.ReadOnly.read_timestamp and
- # TransactionOptions.ReadOnly.exact_staleness.
- #
- # ### Bounded Staleness
- #
- # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
- # subject to a user-provided staleness bound. Cloud Spanner chooses the
- # newest timestamp within the staleness bound that allows execution
- # of the reads at the closest available replica without blocking.
- #
- # All rows yielded are consistent with each other -- if any part of
- # the read observes a transaction, all parts of the read see the
- # transaction. Boundedly stale reads are not repeatable: two stale
- # reads, even if they use the same staleness bound, can execute at
- # different timestamps and thus return inconsistent results.
- #
- # Boundedly stale reads execute in two phases: the first phase
- # negotiates a timestamp among all replicas needed to serve the
- # read. In the second phase, reads are executed at the negotiated
- # timestamp.
- #
- # As a result of the two phase execution, bounded staleness reads are
- # usually a little slower than comparable exact staleness
- # reads. However, they are typically able to return fresher
- # results, and are more likely to execute at the closest replica.
- #
- # Because the timestamp negotiation requires up-front knowledge of
- # which rows will be read, it can only be used with single-use
- # read-only transactions.
- #
- # See TransactionOptions.ReadOnly.max_staleness and
- # TransactionOptions.ReadOnly.min_read_timestamp.
- #
- # ### Old Read Timestamps and Garbage Collection
- #
- # Cloud Spanner continuously garbage collects deleted and overwritten data
- # in the background to reclaim storage space. This process is known
- # as "version GC". By default, version GC reclaims versions after they
- # are one hour old. Because of this, Cloud Spanner cannot perform reads
- # at read timestamps more than one hour in the past. This
- # restriction also applies to in-progress reads and/or SQL queries whose
- # timestamp become too old while executing. Reads and SQL queries with
- # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
- #
- # ## Partitioned DML Transactions
- #
- # Partitioned DML transactions are used to execute DML statements with a
- # different execution strategy that provides different, and often better,
- # scalability properties for large, table-wide operations than DML in a
- # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
- # should prefer using ReadWrite transactions.
- #
- # Partitioned DML partitions the keyspace and runs the DML statement on each
- # partition in separate, internal transactions. These transactions commit
- # automatically when complete, and run independently from one another.
- #
- # To reduce lock contention, this execution strategy only acquires read locks
- # on rows that match the WHERE clause of the statement. Additionally, the
- # smaller per-partition transactions hold locks for less time.
- #
- # That said, Partitioned DML is not a drop-in replacement for standard DML used
- # in ReadWrite transactions.
- #
- # - The DML statement must be fully-partitionable. Specifically, the statement
- # must be expressible as the union of many statements which each access only
- # a single row of the table.
- #
- # - The statement is not applied atomically to all rows of the table. Rather,
- # the statement is applied atomically to partitions of the table, in
- # independent transactions. Secondary index rows are updated atomically
- # with the base table rows.
- #
- # - Partitioned DML does not guarantee exactly-once execution semantics
- # against a partition. The statement will be applied at least once to each
- # partition. It is strongly recommended that the DML statement should be
- # idempotent to avoid unexpected results. For instance, it is potentially
- # dangerous to run a statement such as
- # `UPDATE table SET column = column + 1` as it could be run multiple times
- # against some rows.
- #
- # - The partitions are committed automatically - there is no support for
- # Commit or Rollback. If the call returns an error, or if the client issuing
- # the ExecuteSql call dies, it is possible that some rows had the statement
- # executed on them successfully. It is also possible that statement was
- # never executed against other rows.
- #
- # - Partitioned DML transactions may only contain the execution of a single
- # DML statement via ExecuteSql or ExecuteStreamingSql.
- #
- # - If any error is encountered during the execution of the partitioned DML
- # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
- # value that cannot be stored due to schema constraints), then the
- # operation is stopped at that point and an error is returned. It is
- # possible that at this point, some partitions have been committed (or even
- # committed multiple times), and other partitions have not been run at all.
- #
- # Given the above, Partitioned DML is good fit for large, database-wide,
- # operations that are idempotent, such as deleting old rows from a very large
- # table.
- "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
- #
- # Authorization to begin a Partitioned DML transaction requires
- # `spanner.databases.beginPartitionedDmlTransaction` permission
- # on the `session` resource.
- },
- "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
- #
- # Authorization to begin a read-only transaction requires
- # `spanner.databases.beginReadOnlyTransaction` permission
- # on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
- # seconds. Guarantees that all writes that have committed more
- # than the specified number of seconds ago are visible. Because
- # Cloud Spanner chooses the exact timestamp, this mode works even if
- # the client's local clock is substantially skewed from Cloud Spanner
- # commit timestamps.
- #
- # Useful for reading the freshest data available at a nearby
- # replica, while bounding the possible staleness if the local
- # replica has fallen behind.
- #
- # Note that this option can only be used in single-use
- # transactions.
- "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
- # the Transaction message that describes the transaction.
- "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
- # old. The timestamp is chosen soon after the read is started.
- #
- # Guarantees that all writes that have committed more than the
- # specified number of seconds ago are visible. Because Cloud Spanner
- # chooses the exact timestamp, this mode works even if the client's
- # local clock is substantially skewed from Cloud Spanner commit
- # timestamps.
- #
- # Useful for reading at nearby replicas without the distributed
- # timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
- },
- "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
- #
- # Authorization to begin a read-write transaction requires
- # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
- # on the `session` resource.
- # transaction type has no options.
- },
- },
+ "id": "A String", # Execute the read or SQL query in a previously-started transaction.
"begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in
# it. The transaction ID of the new transaction is returned in
# ResultSetMetadata.transaction, which is a Transaction.
@@ -8100,33 +7614,18 @@
# `spanner.databases.beginPartitionedDmlTransaction` permission
# on the `session` resource.
},
+ "readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
+ #
+ # Authorization to begin a read-write transaction requires
+ # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
+ # on the `session` resource.
+ # transaction type has no options.
+ },
"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
#
# Authorization to begin a read-only transaction requires
# `spanner.databases.beginReadOnlyTransaction` permission
# on the `session` resource.
- "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
- #
- # This is useful for requesting fresher data than some previous
- # read, or data that is fresh enough to observe the effects of some
- # previously committed transaction whose timestamp is known.
- #
- # Note that this option can only be used in single-use transactions.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
- "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
- # reads at a specific timestamp are repeatable; the same read at
- # the same timestamp always returns the same data. If the
- # timestamp is in the future, the read will block until the
- # specified timestamp, modulo the read's deadline.
- #
- # Useful for large scale consistent reads such as mapreduces, or
- # for coordinating many reads against a consistent snapshot of the
- # data.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
# seconds. Guarantees that all writes that have committed more
# than the specified number of seconds ago are visible. Because
@@ -8140,6 +7639,18 @@
#
# Note that this option can only be used in single-use
# transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
# the Transaction message that describes the transaction.
"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
@@ -8153,8 +7664,304 @@
#
# Useful for reading at nearby replicas without the distributed
# timestamp negotiation overhead of `max_staleness`.
- "strong": True or False, # Read at a timestamp where all previously committed transactions
- # are visible.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
+ },
+ "singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.
+ # This is the most efficient way to execute a transaction that
+ # consists of a single SQL query.
+ #
+ #
+ # Each session can have at most one active transaction at a time. After the
+ # active transaction is completed, the session can immediately be
+ # re-used for the next transaction. It is not necessary to create a
+ # new session for each transaction.
+ #
+ # # Transaction Modes
+ #
+ # Cloud Spanner supports three transaction modes:
+ #
+ # 1. Locking read-write. This type of transaction is the only way
+ # to write data into Cloud Spanner. These transactions rely on
+ # pessimistic locking and, if necessary, two-phase commit.
+ # Locking read-write transactions may abort, requiring the
+ # application to retry.
+ #
+ # 2. Snapshot read-only. 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. Snapshot read-only
+ # transactions do not need to be committed.
+ #
+ # 3. Partitioned DML. This type of transaction is used to execute
+ # a single Partitioned DML statement. Partitioned DML partitions
+ # the key space and runs the DML statement over each partition
+ # in parallel using separate, internal transactions that commit
+ # independently. Partitioned DML transactions do not need to be
+ # committed.
+ #
+ # For transactions that only read, snapshot read-only transactions
+ # provide simpler semantics and are almost always faster. In
+ # particular, read-only transactions do not take locks, so they do
+ # not conflict with read-write transactions. As a consequence of not
+ # taking locks, they also do not abort, so retry loops are not needed.
+ #
+ # Transactions may only read/write data in a single database. They
+ # may, however, read/write data in different tables within that
+ # database.
+ #
+ # ## Locking Read-Write Transactions
+ #
+ # Locking transactions may be used to atomically read-modify-write
+ # data anywhere in a database. This type of transaction is externally
+ # consistent.
+ #
+ # Clients should attempt to minimize the amount of time a transaction
+ # is active. Faster transactions commit with higher probability
+ # and cause less contention. Cloud Spanner attempts to keep read locks
+ # active as long as the transaction continues to do reads, and the
+ # transaction has not been terminated by
+ # Commit or
+ # Rollback. Long periods of
+ # inactivity at the client may cause Cloud Spanner to release a
+ # transaction's locks and abort it.
+ #
+ # Conceptually, a read-write transaction consists of zero or more
+ # reads or SQL statements followed by
+ # Commit. At any time before
+ # Commit, the client can send a
+ # Rollback request to abort the
+ # transaction.
+ #
+ # ### Semantics
+ #
+ # Cloud Spanner can commit the transaction if all read locks it acquired
+ # are still valid at commit time, and it is able to acquire write
+ # locks for all writes. Cloud Spanner can abort the transaction for any
+ # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
+ # that the transaction has not modified any user data in Cloud Spanner.
+ #
+ # Unless the transaction commits, Cloud Spanner makes no guarantees about
+ # how long the transaction's locks were held for. It is an error to
+ # use Cloud Spanner locks for any sort of mutual exclusion other than
+ # between Cloud Spanner transactions themselves.
+ #
+ # ### Retrying Aborted Transactions
+ #
+ # When a transaction aborts, the application can choose to retry the
+ # whole transaction again. To maximize the chances of successfully
+ # committing the retry, the client should execute the retry in the
+ # same session as the original attempt. The original session's lock
+ # priority increases with each consecutive abort, meaning that each
+ # attempt has a slightly better chance of success than the previous.
+ #
+ # Under some circumstances (e.g., many transactions attempting to
+ # modify the same row(s)), a transaction can abort many times in a
+ # short period before successfully committing. Thus, it is not a good
+ # idea to cap the number of retries a transaction can attempt;
+ # instead, it is better to limit the total amount of wall time spent
+ # retrying.
+ #
+ # ### Idle Transactions
+ #
+ # A transaction is considered idle if it has no outstanding reads or
+ # SQL queries and has not started a read or SQL query within the last 10
+ # seconds. Idle transactions can be aborted by Cloud Spanner so that they
+ # don't hold on to locks indefinitely. In that case, the commit will
+ # fail with error `ABORTED`.
+ #
+ # If this behavior is undesirable, periodically executing a simple
+ # SQL query in the transaction (e.g., `SELECT 1`) prevents the
+ # transaction from becoming idle.
+ #
+ # ## Snapshot Read-Only Transactions
+ #
+ # Snapshot read-only transactions provides a simpler method than
+ # locking read-write transactions for doing several consistent
+ # reads. However, this type of transaction does not support writes.
+ #
+ # Snapshot transactions do not take locks. Instead, they work by
+ # choosing a Cloud Spanner timestamp, then executing all reads at that
+ # timestamp. Since they do not acquire locks, they do not block
+ # concurrent read-write transactions.
+ #
+ # Unlike locking read-write transactions, snapshot read-only
+ # transactions never abort. They can fail if the chosen read
+ # timestamp is garbage collected; however, the default garbage
+ # collection policy is generous enough that most applications do not
+ # need to worry about this in practice.
+ #
+ # Snapshot read-only transactions do not need to call
+ # Commit or
+ # Rollback (and in fact are not
+ # permitted to do so).
+ #
+ # To execute a snapshot transaction, the client specifies a timestamp
+ # bound, which tells Cloud Spanner how to choose a read timestamp.
+ #
+ # The types of timestamp bound are:
+ #
+ # - Strong (the default).
+ # - Bounded staleness.
+ # - Exact staleness.
+ #
+ # If the Cloud Spanner database to be read is geographically distributed,
+ # stale read-only transactions can execute more quickly than strong
+ # or read-write transaction, because they are able to execute far
+ # from the leader replica.
+ #
+ # Each type of timestamp bound is discussed in detail below.
+ #
+ # ### Strong
+ #
+ # Strong reads are guaranteed to see the effects of all transactions
+ # that have committed before the start of the read. Furthermore, all
+ # rows yielded by a single read are consistent with each other -- if
+ # any part of the read observes a transaction, all parts of the read
+ # see the transaction.
+ #
+ # Strong reads are not repeatable: two consecutive strong read-only
+ # transactions might return inconsistent results if there are
+ # concurrent writes. If consistency across reads is required, the
+ # reads should be executed within a transaction or at an exact read
+ # timestamp.
+ #
+ # See TransactionOptions.ReadOnly.strong.
+ #
+ # ### Exact Staleness
+ #
+ # These timestamp bounds execute reads at a user-specified
+ # timestamp. Reads at a timestamp are guaranteed to see a consistent
+ # prefix of the global transaction history: they observe
+ # modifications done by all transactions with a commit timestamp <=
+ # the read timestamp, and observe none of the modifications done by
+ # transactions with a larger commit timestamp. They will block until
+ # all conflicting transactions that may be assigned commit timestamps
+ # <= the read timestamp have finished.
+ #
+ # The timestamp can either be expressed as an absolute Cloud Spanner commit
+ # timestamp or a staleness relative to the current time.
+ #
+ # These modes do not require a "negotiation phase" to pick a
+ # timestamp. As a result, they execute slightly faster than the
+ # equivalent boundedly stale concurrency modes. On the other hand,
+ # boundedly stale reads usually return fresher results.
+ #
+ # See TransactionOptions.ReadOnly.read_timestamp and
+ # TransactionOptions.ReadOnly.exact_staleness.
+ #
+ # ### Bounded Staleness
+ #
+ # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
+ # subject to a user-provided staleness bound. Cloud Spanner chooses the
+ # newest timestamp within the staleness bound that allows execution
+ # of the reads at the closest available replica without blocking.
+ #
+ # All rows yielded are consistent with each other -- if any part of
+ # the read observes a transaction, all parts of the read see the
+ # transaction. Boundedly stale reads are not repeatable: two stale
+ # reads, even if they use the same staleness bound, can execute at
+ # different timestamps and thus return inconsistent results.
+ #
+ # Boundedly stale reads execute in two phases: the first phase
+ # negotiates a timestamp among all replicas needed to serve the
+ # read. In the second phase, reads are executed at the negotiated
+ # timestamp.
+ #
+ # As a result of the two phase execution, bounded staleness reads are
+ # usually a little slower than comparable exact staleness
+ # reads. However, they are typically able to return fresher
+ # results, and are more likely to execute at the closest replica.
+ #
+ # Because the timestamp negotiation requires up-front knowledge of
+ # which rows will be read, it can only be used with single-use
+ # read-only transactions.
+ #
+ # See TransactionOptions.ReadOnly.max_staleness and
+ # TransactionOptions.ReadOnly.min_read_timestamp.
+ #
+ # ### Old Read Timestamps and Garbage Collection
+ #
+ # Cloud Spanner continuously garbage collects deleted and overwritten data
+ # in the background to reclaim storage space. This process is known
+ # as "version GC". By default, version GC reclaims versions after they
+ # are one hour old. Because of this, Cloud Spanner cannot perform reads
+ # at read timestamps more than one hour in the past. This
+ # restriction also applies to in-progress reads and/or SQL queries whose
+ # timestamp become too old while executing. Reads and SQL queries with
+ # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
+ #
+ # ## Partitioned DML Transactions
+ #
+ # Partitioned DML transactions are used to execute DML statements with a
+ # different execution strategy that provides different, and often better,
+ # scalability properties for large, table-wide operations than DML in a
+ # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+ # should prefer using ReadWrite transactions.
+ #
+ # Partitioned DML partitions the keyspace and runs the DML statement on each
+ # partition in separate, internal transactions. These transactions commit
+ # automatically when complete, and run independently from one another.
+ #
+ # To reduce lock contention, this execution strategy only acquires read locks
+ # on rows that match the WHERE clause of the statement. Additionally, the
+ # smaller per-partition transactions hold locks for less time.
+ #
+ # That said, Partitioned DML is not a drop-in replacement for standard DML used
+ # in ReadWrite transactions.
+ #
+ # - The DML statement must be fully-partitionable. Specifically, the statement
+ # must be expressible as the union of many statements which each access only
+ # a single row of the table.
+ #
+ # - The statement is not applied atomically to all rows of the table. Rather,
+ # the statement is applied atomically to partitions of the table, in
+ # independent transactions. Secondary index rows are updated atomically
+ # with the base table rows.
+ #
+ # - Partitioned DML does not guarantee exactly-once execution semantics
+ # against a partition. The statement will be applied at least once to each
+ # partition. It is strongly recommended that the DML statement should be
+ # idempotent to avoid unexpected results. For instance, it is potentially
+ # dangerous to run a statement such as
+ # `UPDATE table SET column = column + 1` as it could be run multiple times
+ # against some rows.
+ #
+ # - The partitions are committed automatically - there is no support for
+ # Commit or Rollback. If the call returns an error, or if the client issuing
+ # the ExecuteSql call dies, it is possible that some rows had the statement
+ # executed on them successfully. It is also possible that statement was
+ # never executed against other rows.
+ #
+ # - Partitioned DML transactions may only contain the execution of a single
+ # DML statement via ExecuteSql or ExecuteStreamingSql.
+ #
+ # - If any error is encountered during the execution of the partitioned DML
+ # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
+ # value that cannot be stored due to schema constraints), then the
+ # operation is stopped at that point and an error is returned. It is
+ # possible that at this point, some partitions have been committed (or even
+ # committed multiple times), and other partitions have not been run at all.
+ #
+ # Given the above, Partitioned DML is good fit for large, database-wide,
+ # operations that are idempotent, such as deleting old rows from a very large
+ # table.
+ "partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
+ #
+ # Authorization to begin a Partitioned DML transaction requires
+ # `spanner.databases.beginPartitionedDmlTransaction` permission
+ # on the `session` resource.
},
"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
#
@@ -8163,23 +7970,222 @@
# on the `session` resource.
# transaction type has no options.
},
+ "readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.
+ #
+ # Authorization to begin a read-only transaction requires
+ # `spanner.databases.beginReadOnlyTransaction` permission
+ # on the `session` resource.
+ "maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`
+ # seconds. Guarantees that all writes that have committed more
+ # than the specified number of seconds ago are visible. Because
+ # Cloud Spanner chooses the exact timestamp, this mode works even if
+ # the client's local clock is substantially skewed from Cloud Spanner
+ # commit timestamps.
+ #
+ # Useful for reading the freshest data available at a nearby
+ # replica, while bounding the possible staleness if the local
+ # replica has fallen behind.
+ #
+ # Note that this option can only be used in single-use
+ # transactions.
+ "minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.
+ #
+ # This is useful for requesting fresher data than some previous
+ # read, or data that is fresh enough to observe the effects of some
+ # previously committed transaction whose timestamp is known.
+ #
+ # Note that this option can only be used in single-use transactions.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ "strong": True or False, # Read at a timestamp where all previously committed transactions
+ # are visible.
+ "returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in
+ # the Transaction message that describes the transaction.
+ "exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`
+ # old. The timestamp is chosen soon after the read is started.
+ #
+ # Guarantees that all writes that have committed more than the
+ # specified number of seconds ago are visible. Because Cloud Spanner
+ # chooses the exact timestamp, this mode works even if the client's
+ # local clock is substantially skewed from Cloud Spanner commit
+ # timestamps.
+ #
+ # Useful for reading at nearby replicas without the distributed
+ # timestamp negotiation overhead of `max_staleness`.
+ "readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,
+ # reads at a specific timestamp are repeatable; the same read at
+ # the same timestamp always returns the same data. If the
+ # timestamp is in the future, the read will block until the
+ # specified timestamp, modulo the read's deadline.
+ #
+ # Useful for large scale consistent reads such as mapreduces, or
+ # for coordinating many reads against a consistent snapshot of the
+ # data.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
+ },
},
- "id": "A String", # Execute the read or SQL query in a previously-started transaction.
},
+ "partitionToken": "A String", # If present, results will be restricted to the specified partition
+ # previously created using PartitionRead(). There must be an exact
+ # match for the values of fields common to this message and the
+ # PartitionReadRequest message used to create this partition_token.
+ "columns": [ # Required. The columns of table to be returned for each row matching
+ # this request.
+ "A String",
+ ],
+ "limit": "A String", # If greater than zero, only the first `limit` rows are yielded. If `limit`
+ # is zero, the default is no limit. A limit cannot be specified if
+ # `partition_token` is set.
+ "table": "A String", # Required. The name of the table in the database to be read.
"resumeToken": "A String", # If this request is resuming a previously interrupted read,
# `resume_token` should be copied from the last
# PartialResultSet yielded before the interruption. Doing this
# enables the new read to resume where the last read left off. The
# rest of the request parameters must exactly match the request
# that yielded this token.
- "partitionToken": "A String", # If present, results will be restricted to the specified partition
- # previously created using PartitionRead(). There must be an exact
- # match for the values of fields common to this message and the
- # PartitionReadRequest message used to create this partition_token.
- "table": "A String", # Required. The name of the table in the database to be read.
- "limit": "A String", # If greater than zero, only the first `limit` rows are yielded. If `limit`
- # is zero, the default is no limit. A limit cannot be specified if
- # `partition_token` is set.
+ "keySet": { # `KeySet` defines a collection of Cloud Spanner keys and/or key ranges. All # Required. `key_set` identifies the rows to be yielded. `key_set` names the
+ # primary keys of the rows in table to be yielded, unless index
+ # is present. If index is present, then key_set instead names
+ # index keys in index.
+ #
+ # If the partition_token field is empty, rows are yielded
+ # in table primary key order (if index is empty) or index key order
+ # (if index is non-empty). If the partition_token field is not
+ # empty, rows will be yielded in an unspecified order.
+ #
+ # It is not an error for the `key_set` to name rows that do not
+ # exist in the database. Read yields nothing for nonexistent rows.
+ # the keys are expected to be in the same table or index. The keys need
+ # not be sorted in any particular way.
+ #
+ # If the same key is specified multiple times in the set (for example
+ # if two ranges, two keys, or a key and a range overlap), Cloud Spanner
+ # behaves as if the key were only specified once.
+ "ranges": [ # A list of key ranges. See KeyRange for more information about
+ # key range specifications.
+ { # KeyRange represents a range of rows in a table or index.
+ #
+ # A range has a start key and an end key. These keys can be open or
+ # closed, indicating if the range includes rows with that key.
+ #
+ # Keys are represented by lists, where the ith value in the list
+ # corresponds to the ith component of the table or index primary key.
+ # Individual values are encoded as described
+ # here.
+ #
+ # For example, consider the following table definition:
+ #
+ # CREATE TABLE UserEvents (
+ # UserName STRING(MAX),
+ # EventDate STRING(10)
+ # ) PRIMARY KEY(UserName, EventDate);
+ #
+ # The following keys name rows in this table:
+ #
+ # "Bob", "2014-09-23"
+ #
+ # Since the `UserEvents` table's `PRIMARY KEY` clause names two
+ # columns, each `UserEvents` key has two elements; the first is the
+ # `UserName`, and the second is the `EventDate`.
+ #
+ # Key ranges with multiple components are interpreted
+ # lexicographically by component using the table or index key's declared
+ # sort order. For example, the following range returns all events for
+ # user `"Bob"` that occurred in the year 2015:
+ #
+ # "start_closed": ["Bob", "2015-01-01"]
+ # "end_closed": ["Bob", "2015-12-31"]
+ #
+ # Start and end keys can omit trailing key components. This affects the
+ # inclusion and exclusion of rows that exactly match the provided key
+ # components: if the key is closed, then rows that exactly match the
+ # provided components are included; if the key is open, then rows
+ # that exactly match are not included.
+ #
+ # For example, the following range includes all events for `"Bob"` that
+ # occurred during and after the year 2000:
+ #
+ # "start_closed": ["Bob", "2000-01-01"]
+ # "end_closed": ["Bob"]
+ #
+ # The next example retrieves all events for `"Bob"`:
+ #
+ # "start_closed": ["Bob"]
+ # "end_closed": ["Bob"]
+ #
+ # To retrieve events before the year 2000:
+ #
+ # "start_closed": ["Bob"]
+ # "end_open": ["Bob", "2000-01-01"]
+ #
+ # The following range includes all rows in the table:
+ #
+ # "start_closed": []
+ # "end_closed": []
+ #
+ # This range returns all users whose `UserName` begins with any
+ # character from A to C:
+ #
+ # "start_closed": ["A"]
+ # "end_open": ["D"]
+ #
+ # This range returns all users whose `UserName` begins with B:
+ #
+ # "start_closed": ["B"]
+ # "end_open": ["C"]
+ #
+ # Key ranges honor column sort order. For example, suppose a table is
+ # defined as follows:
+ #
+ # CREATE TABLE DescendingSortedTable {
+ # Key INT64,
+ # ...
+ # ) PRIMARY KEY(Key DESC);
+ #
+ # The following range retrieves all rows with key values between 1
+ # and 100 inclusive:
+ #
+ # "start_closed": ["100"]
+ # "end_closed": ["1"]
+ #
+ # Note that 100 is passed as the start, and 1 is passed as the end,
+ # because `Key` is a descending column in the schema.
+ "startOpen": [ # If the start is open, then the range excludes rows whose first
+ # `len(start_open)` key columns exactly match `start_open`.
+ "",
+ ],
+ "endClosed": [ # If the end is closed, then the range includes all rows whose
+ # first `len(end_closed)` key columns exactly match `end_closed`.
+ "",
+ ],
+ "endOpen": [ # If the end is open, then the range excludes rows whose first
+ # `len(end_open)` key columns exactly match `end_open`.
+ "",
+ ],
+ "startClosed": [ # If the start is closed, then the range includes all rows whose
+ # first `len(start_closed)` key columns exactly match `start_closed`.
+ "",
+ ],
+ },
+ ],
+ "keys": [ # A list of specific keys. Entries in `keys` should have exactly as
+ # many elements as there are columns in the primary or index key
+ # with which this `KeySet` is used. Individual key values are
+ # encoded as described here.
+ [
+ "",
+ ],
+ ],
+ "all": True or False, # For convenience `all` can be set to `true` to indicate that this
+ # `KeySet` matches all keys in the table or index. Note that any keys
+ # specified in `keys` or `ranges` are only yielded once.
+ },
+ "index": "A String", # If non-empty, the name of an index on table. This index is
+ # used instead of the table primary key when interpreting key_set
+ # and sorting result rows. See key_set for further information.
}
x__xgafv: string, V1 error format.
@@ -8193,6 +8199,90 @@
{ # Partial results from a streaming read or SQL query. Streaming reads and
# SQL queries better tolerate large result sets, large rows, and large
# values, but are a little trickier to consume.
+ "stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the statement that produced this
+ # streaming result set. These can be requested by setting
+ # ExecuteSqlRequest.query_mode and are sent
+ # only once with the last response in the stream.
+ # This field will also be present in the last response for DML
+ # statements.
+ "rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it
+ # returns a lower bound of the rows modified.
+ "queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
+ "planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
+ # with the plan root. Each PlanNode's `id` corresponds to its index in
+ # `plan_nodes`.
+ { # Node information for nodes appearing in a QueryPlan.plan_nodes.
+ "displayName": "A String", # The display name for the node.
+ "executionStats": { # The execution statistics associated with the node, contained in a group of
+ # key-value pairs. Only present if the plan was returned as a result of a
+ # profile query. For example, number of executions, number of rows/time per
+ # execution etc.
+ "a_key": "", # Properties of the object.
+ },
+ "shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
+ # `SCALAR` PlanNode(s).
+ "subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases
+ # where the `description` string of this node references a `SCALAR`
+ # subquery contained in the expression subtree rooted at this node. The
+ # referenced `SCALAR` subquery may not necessarily be a direct child of
+ # this node.
+ "a_key": 42,
+ },
+ "description": "A String", # A string representation of the expression subtree rooted at this node.
+ },
+ "metadata": { # Attributes relevant to the node contained in a group of key-value pairs.
+ # For example, a Parameter Reference node could have the following
+ # information in its metadata:
+ #
+ # {
+ # "parameter_reference": "param1",
+ # "parameter_type": "array"
+ # }
+ "a_key": "", # Properties of the object.
+ },
+ "childLinks": [ # List of child node `index`es and their relationship to this parent.
+ { # Metadata associated with a parent-child relationship appearing in a
+ # PlanNode.
+ "type": "A String", # The type of the link. For example, in Hash Joins this could be used to
+ # distinguish between the build child and the probe child, or in the case
+ # of the child being an output variable, to represent the tag associated
+ # with the output variable.
+ "variable": "A String", # Only present if the child node is SCALAR and corresponds
+ # to an output variable of the parent node. The field carries the name of
+ # the output variable.
+ # For example, a `TableScan` operator that reads rows from a table will
+ # have child links to the `SCALAR` nodes representing the output variables
+ # created for each column that is read by the operator. The corresponding
+ # `variable` fields will be set to the variable names assigned to the
+ # columns.
+ "childIndex": 42, # The node to which the link points.
+ },
+ ],
+ "index": 42, # The `PlanNode`'s index in node list.
+ "kind": "A String", # Used to determine the type of node. May be needed for visualizing
+ # different kinds of nodes differently. For example, If the node is a
+ # SCALAR node, it will have a condensed representation
+ # which can be used to directly embed a description of the node in its
+ # parent.
+ },
+ ],
+ },
+ "rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.
+ "queryStats": { # Aggregated statistics from the execution of the query. Only present when
+ # the query is profiled. For example, a query could return the statistics as
+ # follows:
+ #
+ # {
+ # "rows_returned": "3",
+ # "elapsed_time": "1.22 secs",
+ # "cpu_time": "1.19 secs"
+ # }
+ "a_key": "", # Properties of the object.
+ },
+ },
+ "chunkedValue": True or False, # If true, then the final value in values is chunked, and must
+ # be combined with more values from subsequent `PartialResultSet`s
+ # to obtain a complete field value.
"values": [ # A streamed result set consists of a stream of values, which might
# be split into many `PartialResultSet` messages to accommodate
# large rows and/or large values. Every N complete values defines a
@@ -8298,6 +8388,12 @@
},
"transaction": { # A transaction. # If the read or SQL query began a transaction as a side-effect, the
# information about the new transaction is yielded here.
+ "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
+ # for the transaction. Not returned by default: see
+ # TransactionOptions.ReadOnly.return_read_timestamp.
+ #
+ # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
"id": "A String", # `id` may be used to identify the transaction in subsequent
# Read,
# ExecuteSql,
@@ -8306,12 +8402,6 @@
#
# Single-use read-only transactions do not have IDs, because
# single-use transactions do not support multiple requests.
- "readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen
- # for the transaction. Not returned by default: see
- # TransactionOptions.ReadOnly.return_read_timestamp.
- #
- # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
- # Example: `"2014-10-02T15:01:23.045123456Z"`.
},
},
"resumeToken": "A String", # Streaming calls might be interrupted for a variety of reasons, such
@@ -8319,90 +8409,6 @@
# be resumed by re-sending the original request and including
# `resume_token`. Note that executing any other transaction in the
# same session invalidates the token.
- "stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the statement that produced this
- # streaming result set. These can be requested by setting
- # ExecuteSqlRequest.query_mode and are sent
- # only once with the last response in the stream.
- # This field will also be present in the last response for DML
- # statements.
- "rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.
- "queryStats": { # Aggregated statistics from the execution of the query. Only present when
- # the query is profiled. For example, a query could return the statistics as
- # follows:
- #
- # {
- # "rows_returned": "3",
- # "elapsed_time": "1.22 secs",
- # "cpu_time": "1.19 secs"
- # }
- "a_key": "", # Properties of the object.
- },
- "rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it
- # returns a lower bound of the rows modified.
- "queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
- "planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
- # with the plan root. Each PlanNode's `id` corresponds to its index in
- # `plan_nodes`.
- { # Node information for nodes appearing in a QueryPlan.plan_nodes.
- "metadata": { # Attributes relevant to the node contained in a group of key-value pairs.
- # For example, a Parameter Reference node could have the following
- # information in its metadata:
- #
- # {
- # "parameter_reference": "param1",
- # "parameter_type": "array"
- # }
- "a_key": "", # Properties of the object.
- },
- "executionStats": { # The execution statistics associated with the node, contained in a group of
- # key-value pairs. Only present if the plan was returned as a result of a
- # profile query. For example, number of executions, number of rows/time per
- # execution etc.
- "a_key": "", # Properties of the object.
- },
- "shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
- # `SCALAR` PlanNode(s).
- "description": "A String", # A string representation of the expression subtree rooted at this node.
- "subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases
- # where the `description` string of this node references a `SCALAR`
- # subquery contained in the expression subtree rooted at this node. The
- # referenced `SCALAR` subquery may not necessarily be a direct child of
- # this node.
- "a_key": 42,
- },
- },
- "index": 42, # The `PlanNode`'s index in node list.
- "kind": "A String", # Used to determine the type of node. May be needed for visualizing
- # different kinds of nodes differently. For example, If the node is a
- # SCALAR node, it will have a condensed representation
- # which can be used to directly embed a description of the node in its
- # parent.
- "displayName": "A String", # The display name for the node.
- "childLinks": [ # List of child node `index`es and their relationship to this parent.
- { # Metadata associated with a parent-child relationship appearing in a
- # PlanNode.
- "variable": "A String", # Only present if the child node is SCALAR and corresponds
- # to an output variable of the parent node. The field carries the name of
- # the output variable.
- # For example, a `TableScan` operator that reads rows from a table will
- # have child links to the `SCALAR` nodes representing the output variables
- # created for each column that is read by the operator. The corresponding
- # `variable` fields will be set to the variable names assigned to the
- # columns.
- "childIndex": 42, # The node to which the link points.
- "type": "A String", # The type of the link. For example, in Hash Joins this could be used to
- # distinguish between the build child and the probe child, or in the case
- # of the child being an output variable, to represent the tag associated
- # with the output variable.
- },
- ],
- },
- ],
- },
- },
- "chunkedValue": True or False, # If true, then the final value in values is chunked, and must
- # be combined with more values from subsequent `PartialResultSet`s
- # to obtain a complete field value.
}</pre>
</div>