google-cloud-spanner 1.6.3 → 1.6.4

data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/transaction.rb

@@ -25,7 +25,7 @@ module Google
       #
       # = Transaction Modes
       #
-      # Cloud Spanner supports two 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
@@ -39,6 +39,13 @@ module Google
       #      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
@@ -65,11 +72,8 @@ module Google
       # inactivity at the client may cause Cloud Spanner to release a
       # transaction's locks and abort it.
       #
-      # Reads performed within a transaction acquire locks on the data
-      # being read. Writes can only be done at commit time, after all reads
-      # have been completed.
       # Conceptually, a read-write transaction consists of zero or more
-      # reads or SQL queries followed by
+      # reads or SQL statements followed by
       # {Google::Spanner::V1::Spanner::Commit Commit}. At any time before
       # {Google::Spanner::V1::Spanner::Commit Commit}, the client can send a
       # {Google::Spanner::V1::Spanner::Rollback Rollback} request to abort the
@@ -80,7 +84,7 @@ module Google
       # 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
+      # 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
@@ -110,10 +114,10 @@ module Google
       # 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+.
+      # fail with error `ABORTED`.
       #
       # If this behavior is undesirable, periodically executing a simple
-      # SQL query in the transaction (e.g., +SELECT 1+) prevents the
+      # SQL query in the transaction (e.g., `SELECT 1`) prevents the
       # transaction from becoming idle.
       #
       # == Snapshot Read-Only Transactions
@@ -231,26 +235,92 @@ module Google
       # 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+.
+      # 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.
       # @!attribute [rw] read_write
       #   @return [Google::Spanner::V1::TransactionOptions::ReadWrite]
       #     Transaction may write.
       #
       #     Authorization to begin a read-write transaction requires
-      #     +spanner.databases.beginOrRollbackReadWriteTransaction+ permission
-      #     on the +session+ resource.
+      #     `spanner.databases.beginOrRollbackReadWriteTransaction` permission
+      #     on the `session` resource.
+      # @!attribute [rw] partitioned_dml
+      #   @return [Google::Spanner::V1::TransactionOptions::PartitionedDml]
+      #     Partitioned DML transaction.
+      #
+      #     Authorization to begin a Partitioned DML transaction requires
+      #     `spanner.databases.beginPartitionedDmlTransaction` permission
+      #     on the `session` resource.
       # @!attribute [rw] read_only
       #   @return [Google::Spanner::V1::TransactionOptions::ReadOnly]
       #     Transaction will not write.
       #
       #     Authorization to begin a read-only transaction requires
-      #     +spanner.databases.beginReadOnlyTransaction+ permission
-      #     on the +session+ resource.
+      #     `spanner.databases.beginReadOnlyTransaction` permission
+      #     on the `session` resource.
       class TransactionOptions
         # Message type to initiate a read-write transaction. Currently this
         # transaction type has no options.
         class ReadWrite; end
 
+        # Message type to initiate a Partitioned DML transaction.
+        class PartitionedDml; end
+
         # Message type to initiate a read-only transaction.
         # @!attribute [rw] strong
         #   @return [true, false]
@@ -258,7 +328,7 @@ module Google
         #     are visible.
         # @!attribute [rw] min_read_timestamp
         #   @return [Google::Protobuf::Timestamp]
-        #     Executes all reads at a timestamp >= +min_read_timestamp+.
+        #     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
@@ -267,10 +337,10 @@ module Google
         #     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"+.
+        #     Example: `"2014-10-02T15:01:23.045123456Z"`.
         # @!attribute [rw] max_staleness
         #   @return [Google::Protobuf::Duration]
-        #     Read data at a timestamp >= +NOW - max_staleness+
+        #     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
@@ -296,10 +366,10 @@ module Google
         #     data.
         #
         #     A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
-        #     Example: +"2014-10-02T15:01:23.045123456Z"+.
+        #     Example: `"2014-10-02T15:01:23.045123456Z"`.
         # @!attribute [rw] exact_staleness
         #   @return [Google::Protobuf::Duration]
-        #     Executes all reads at a timestamp that is +exact_staleness+
+        #     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
@@ -309,7 +379,7 @@ module Google
         #     timestamps.
         #
         #     Useful for reading at nearby replicas without the distributed
-        #     timestamp negotiation overhead of +max_staleness+.
+        #     timestamp negotiation overhead of `max_staleness`.
         # @!attribute [rw] return_read_timestamp
         #   @return [true, false]
         #     If true, the Cloud Spanner-selected read timestamp is included in
@@ -320,7 +390,7 @@ module Google
       # A transaction.
       # @!attribute [rw] id
       #   @return [String]
-      #     +id+ may be used to identify the transaction in subsequent
+      #     `id` may be used to identify the transaction in subsequent
       #     {Google::Spanner::V1::Spanner::Read Read},
       #     {Google::Spanner::V1::Spanner::ExecuteSql ExecuteSql},
       #     {Google::Spanner::V1::Spanner::Commit Commit}, or
@@ -335,7 +405,7 @@ module Google
       #     {Google::Spanner::V1::TransactionOptions::ReadOnly#return_read_timestamp TransactionOptions::ReadOnly#return_read_timestamp}.
       #
       #     A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
-      #     Example: +"2014-10-02T15:01:23.045123456Z"+.
+      #     Example: `"2014-10-02T15:01:23.045123456Z"`.
       class Transaction; end
 
       # This message is used to select the transaction in which a

data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/type.rb

@@ -16,22 +16,22 @@
 module Google
   module Spanner
     module V1
-      # +Type+ indicates the type of a Cloud Spanner value, as might be stored in a
+      # `Type` indicates the type of a Cloud Spanner value, as might be stored in a
       # table cell or returned from an SQL query.
       # @!attribute [rw] code
       #   @return [Google::Spanner::V1::TypeCode]
       #     Required. The {Google::Spanner::V1::TypeCode TypeCode} for this type.
       # @!attribute [rw] array_element_type
       #   @return [Google::Spanner::V1::Type]
-      #     If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::ARRAY ARRAY}, then +array_element_type+
+      #     If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::ARRAY ARRAY}, then `array_element_type`
       #     is the type of the array elements.
       # @!attribute [rw] struct_type
       #   @return [Google::Spanner::V1::StructType]
-      #     If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::STRUCT STRUCT}, then +struct_type+
+      #     If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::STRUCT STRUCT}, then `struct_type`
       #     provides type information for the struct's fields.
       class Type; end
 
-      # +StructType+ defines the fields of a {Google::Spanner::V1::TypeCode::STRUCT STRUCT} type.
+      # `StructType` defines the fields of a {Google::Spanner::V1::TypeCode::STRUCT STRUCT} type.
       # @!attribute [rw] fields
       #   @return [Array<Google::Spanner::V1::StructType::Field>]
       #     The list of fields that make up this struct. Order is
@@ -39,17 +39,17 @@ module Google
       #     lists, where the order of field values matches the order of
       #     fields in the {Google::Spanner::V1::StructType 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.
+      #     fields in the `SELECT` clause of a query.
       class StructType
         # Message representing a single field of a struct.
         # @!attribute [rw] name
         #   @return [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
+        #     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
+        #     UPPER(ColName)"`). Note that a query result can contain
         #     multiple fields with the same name.
         # @!attribute [rw] type
         #   @return [Google::Spanner::V1::Type]
@@ -57,52 +57,52 @@ module Google
         class Field; end
       end
 
-      # +TypeCode+ is used as part of {Google::Spanner::V1::Type Type} to
+      # `TypeCode` is used as part of {Google::Spanner::V1::Type Type} to
       # indicate the type of a Cloud Spanner value.
       #
       # Each legal value of a type can be encoded to or decoded from a JSON
       # value, using the encodings described below. All Cloud Spanner values can
-      # be +null+, regardless of type; +null+s are always encoded as a JSON
-      # +null+.
+      # be `null`, regardless of type; `null`s are always encoded as a JSON
+      # `null`.
       module TypeCode
         # Not specified.
         TYPE_CODE_UNSPECIFIED = 0
 
-        # Encoded as JSON +true+ or +false+.
+        # Encoded as JSON `true` or `false`.
         BOOL = 1
 
-        # Encoded as +string+, in decimal format.
+        # Encoded as `string`, in decimal format.
         INT64 = 2
 
-        # Encoded as +number+, or the strings +"NaN"+, +"Infinity"+, or
-        # +"-Infinity"+.
+        # Encoded as `number`, or the strings `"NaN"`, `"Infinity"`, or
+        # `"-Infinity"`.
         FLOAT64 = 3
 
-        # Encoded as +string+ in RFC 3339 timestamp format. The time zone
-        # must be present, and must be +"Z"+.
+        # Encoded as `string` in RFC 3339 timestamp format. The time zone
+        # must be present, and must be `"Z"`.
         #
         # If the schema has the column option
-        # +allow_commit_timestamp=true+, the placeholder string
-        # +"spanner.commit_timestamp()"+ can be used to instruct the system
+        # `allow_commit_timestamp=true`, the placeholder string
+        # `"spanner.commit_timestamp()"` can be used to instruct the system
         # to insert the commit timestamp associated with the transaction
         # commit.
         TIMESTAMP = 4
 
-        # Encoded as +string+ in RFC 3339 date format.
+        # Encoded as `string` in RFC 3339 date format.
         DATE = 5
 
-        # Encoded as +string+.
+        # Encoded as `string`.
         STRING = 6
 
-        # Encoded as a base64-encoded +string+, as described in RFC 4648,
+        # Encoded as a base64-encoded `string`, as described in RFC 4648,
         # section 4.
         BYTES = 7
 
-        # Encoded as +list+, where the list elements are represented
+        # Encoded as `list`, where the list elements are represented
         # according to {Google::Spanner::V1::Type#array_element_type array_element_type}.
         ARRAY = 8
 
-        # Encoded as +list+, where list element +i+ is represented according
+        # Encoded as `list`, where list element `i` is represented according
         # to [struct_type.fields[i]][google.spanner.v1.StructType.fields].
         STRUCT = 9
       end