Class ReadRequest (3.51.0) 

ReadRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)

The request for Read][google.spanner.v1.Spanner.Read] and StreamingRead][google.spanner.v1.Spanner.StreamingRead].

Attributes
Name Description
session str
Required. The session in which the read should be performed.
transaction google.cloud.spanner_v1.types.TransactionSelector
The transaction to use. If none is provided, the default is a temporary read-only transaction with strong concurrency.
table str
Required. The name of the table in the database to be read.
index str
If non-empty, the name of an index on table][google.spanner.v1.ReadRequest.table]. This index is used instead of the table primary key when interpreting key_set][google.spanner.v1.ReadRequest.key_set] and sorting result rows. See key_set][google.spanner.v1.ReadRequest.key_set] for further information.
columns MutableSequence[str]
Required. The columns of table][google.spanner.v1.ReadRequest.table] to be returned for each row matching this request.
key_set google.cloud.spanner_v1.types.KeySet
Required. key_set identifies the rows to be yielded. key_set names the primary keys of the rows in table][google.spanner.v1.ReadRequest.table] to be yielded, unless index][google.spanner.v1.ReadRequest.index] is present. If index][google.spanner.v1.ReadRequest.index] is present, then key_set][google.spanner.v1.ReadRequest.key_set] instead names index keys in index][google.spanner.v1.ReadRequest.index]. If the partition_token][google.spanner.v1.ReadRequest.partition_token] field is empty, rows are yielded in table primary key order (if index][google.spanner.v1.ReadRequest.index] is empty) or index key order (if index][google.spanner.v1.ReadRequest.index] is non-empty). If the partition_token][google.spanner.v1.ReadRequest.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.
limit int
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.
resume_token bytes
If this request is resuming a previously interrupted read, resume_token should be copied from the last PartialResultSet][google.spanner.v1.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.
partition_token bytes
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.
request_options google.cloud.spanner_v1.types.RequestOptions
Common options for this request.
directed_read_options google.cloud.spanner_v1.types.DirectedReadOptions
Directed read options for this request.
data_boost_enabled bool
If this is for a partitioned read and this field is set to true, the request is executed with Spanner Data Boost independent compute resources. If the field is set to true but the request does not set partition_token, the API returns an INVALID_ARGUMENT error.
order_by google.cloud.spanner_v1.types.ReadRequest.OrderBy
Optional. Order for the returned rows. By default, Spanner will return result rows in primary key order except for PartitionRead requests. For applications that do not require rows to be returned in primary key (ORDER_BY_PRIMARY_KEY) order, setting ORDER_BY_NO_ORDER option allows Spanner to optimize row retrieval, resulting in lower latencies in certain cases (e.g. bulk point lookups).
lock_hint google.cloud.spanner_v1.types.ReadRequest.LockHint
Optional. Lock Hint for the request, it can only be used with read-write transactions.

Classes

LockHint

LockHint(value)

A lock hint mechanism for reads done within a transaction.

    LOCK_HINT_UNSPECIFIED is equivalent to LOCK_HINT_SHARED.
LOCK_HINT_SHARED (1):
    Acquire shared locks.

    By default when you perform a read as part of a read-write
    transaction, Spanner acquires shared read locks, which
    allows other reads to still access the data until your
    transaction is ready to commit. When your transaction is
    committing and writes are being applied, the transaction
    attempts to upgrade to an exclusive lock for any data you
    are writing. For more information about locks, see `Lock
    modes <https://cloud.google.com/spanner/docs/introspection/lock-statistics#explain-lock-modes>`__.
LOCK_HINT_EXCLUSIVE (2):
    Acquire exclusive locks.

    Requesting exclusive locks is beneficial if you observe high
    write contention, which means you notice that multiple
    transactions are concurrently trying to read and write to
    the same data, resulting in a large number of aborts. This
    problem occurs when two transactions initially acquire
    shared locks and then both try to upgrade to exclusive locks
    at the same time. In this situation both transactions are
    waiting for the other to give up their lock, resulting in a
    deadlocked situation. Spanner is able to detect this
    occurring and force one of the transactions to abort.
    However, this is a slow and expensive operation and results
    in lower performance. In this case it makes sense to acquire
    exclusive locks at the start of the transaction because then
    when multiple transactions try to act on the same data, they
    automatically get serialized. Each transaction waits its
    turn to acquire the lock and avoids getting into deadlock
    situations.

    Because the exclusive lock hint is just a hint, it should
    not be considered equivalent to a mutex. In other words, you
    should not use Spanner exclusive locks as a mutual exclusion
    mechanism for the execution of code outside of Spanner.

    **Note:** Request exclusive locks judiciously because they
    block others from reading that data for the entire
    transaction, rather than just when the writes are being
    performed. Unless you observe high write contention, you
    should use the default of shared read locks so you don't
    prematurely block other clients from reading the data that
    you're writing to.

OrderBy

OrderBy(value)

An option to control the order in which rows are returned from a read.

    ORDER_BY_UNSPECIFIED is equivalent to ORDER_BY_PRIMARY_KEY.
ORDER_BY_PRIMARY_KEY (1):
    Read rows are returned in primary key order.

    In the event that this option is used in conjunction with
    the `partition_token` field, the API will return an
    `INVALID_ARGUMENT` error.
ORDER_BY_NO_ORDER (2):
    Read rows are returned in any order.