google-cloud-spanner 1.6.3 → 1.6.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +8 -0
  3. data/LOGGING.md +1 -1
  4. data/OVERVIEW.md +1 -1
  5. data/lib/google/cloud/spanner/admin/database/v1/database_admin_client.rb +29 -29
  6. data/lib/google/cloud/spanner/admin/database/v1/doc/google/iam/v1/iam_policy.rb +13 -13
  7. data/lib/google/cloud/spanner/admin/database/v1/doc/google/iam/v1/policy.rb +28 -28
  8. data/lib/google/cloud/spanner/admin/database/v1/doc/google/longrunning/operations.rb +9 -9
  9. data/lib/google/cloud/spanner/admin/database/v1/doc/google/protobuf/any.rb +8 -8
  10. data/lib/google/cloud/spanner/admin/database/v1/doc/google/protobuf/empty.rb +1 -1
  11. data/lib/google/cloud/spanner/admin/database/v1/doc/google/rpc/status.rb +11 -11
  12. data/lib/google/cloud/spanner/admin/database/v1/doc/google/spanner/admin/database/v1/spanner_database_admin.rb +21 -21
  13. data/lib/google/cloud/spanner/admin/database/v1.rb +4 -4
  14. data/lib/google/cloud/spanner/admin/database.rb +4 -4
  15. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/iam/v1/iam_policy.rb +13 -13
  16. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/iam/v1/policy.rb +28 -28
  17. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/longrunning/operations.rb +9 -9
  18. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/protobuf/any.rb +8 -8
  19. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/protobuf/empty.rb +1 -1
  20. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/protobuf/field_mask.rb +7 -7
  21. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/rpc/status.rb +11 -11
  22. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/spanner/admin/instance/v1/spanner_instance_admin.rb +30 -30
  23. data/lib/google/cloud/spanner/admin/instance/v1/instance_admin_client.rb +44 -44
  24. data/lib/google/cloud/spanner/admin/instance/v1.rb +4 -4
  25. data/lib/google/cloud/spanner/admin/instance.rb +4 -4
  26. data/lib/google/cloud/spanner/v1/doc/google/protobuf/duration.rb +3 -3
  27. data/lib/google/cloud/spanner/v1/doc/google/protobuf/empty.rb +1 -1
  28. data/lib/google/cloud/spanner/v1/doc/google/protobuf/struct.rb +11 -11
  29. data/lib/google/cloud/spanner/v1/doc/google/protobuf/timestamp.rb +7 -7
  30. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/keys.rb +19 -19
  31. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/mutation.rb +6 -6
  32. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/query_plan.rb +11 -11
  33. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/result_set.rb +33 -19
  34. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/spanner.rb +65 -39
  35. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/transaction.rb +91 -21
  36. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/type.rb +25 -25
  37. data/lib/google/cloud/spanner/v1/spanner_client.rb +139 -79
  38. data/lib/google/cloud/spanner/version.rb +1 -1
  39. data/lib/google/spanner/admin/database/v1/spanner_database_admin_services_pb.rb +1 -1
  40. data/lib/google/spanner/admin/instance/v1/spanner_instance_admin_services_pb.rb +1 -1
  41. data/lib/google/spanner/v1/result_set_pb.rb +4 -0
  42. data/lib/google/spanner/v1/spanner_pb.rb +1 -0
  43. data/lib/google/spanner/v1/spanner_services_pb.rb +14 -6
  44. data/lib/google/spanner/v1/transaction_pb.rb +4 -0
  45. data/lib/google-cloud-spanner.rb +1 -1
  46. metadata +3 -3
@@ -25,7 +25,7 @@ module Google
25
25
  #
26
26
  # = Transaction Modes
27
27
  #
28
- # Cloud Spanner supports two transaction modes:
28
+ # Cloud Spanner supports three transaction modes:
29
29
  #
30
30
  # 1. Locking read-write. This type of transaction is the only way
31
31
  # to write data into Cloud Spanner. These transactions rely on
@@ -39,6 +39,13 @@ module Google
39
39
  # read at timestamps in the past. Snapshot read-only
40
40
  # transactions do not need to be committed.
41
41
  #
42
+ # 3. Partitioned DML. This type of transaction is used to execute
43
+ # a single Partitioned DML statement. Partitioned DML partitions
44
+ # the key space and runs the DML statement over each partition
45
+ # in parallel using separate, internal transactions that commit
46
+ # independently. Partitioned DML transactions do not need to be
47
+ # committed.
48
+ #
42
49
  # For transactions that only read, snapshot read-only transactions
43
50
  # provide simpler semantics and are almost always faster. In
44
51
  # particular, read-only transactions do not take locks, so they do
@@ -65,11 +72,8 @@ module Google
65
72
  # inactivity at the client may cause Cloud Spanner to release a
66
73
  # transaction's locks and abort it.
67
74
  #
68
- # Reads performed within a transaction acquire locks on the data
69
- # being read. Writes can only be done at commit time, after all reads
70
- # have been completed.
71
75
  # Conceptually, a read-write transaction consists of zero or more
72
- # reads or SQL queries followed by
76
+ # reads or SQL statements followed by
73
77
  # {Google::Spanner::V1::Spanner::Commit Commit}. At any time before
74
78
  # {Google::Spanner::V1::Spanner::Commit Commit}, the client can send a
75
79
  # {Google::Spanner::V1::Spanner::Rollback Rollback} request to abort the
@@ -80,7 +84,7 @@ module Google
80
84
  # Cloud Spanner can commit the transaction if all read locks it acquired
81
85
  # are still valid at commit time, and it is able to acquire write
82
86
  # locks for all writes. Cloud Spanner can abort the transaction for any
83
- # reason. If a commit attempt returns +ABORTED+, Cloud Spanner guarantees
87
+ # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
84
88
  # that the transaction has not modified any user data in Cloud Spanner.
85
89
  #
86
90
  # Unless the transaction commits, Cloud Spanner makes no guarantees about
@@ -110,10 +114,10 @@ module Google
110
114
  # SQL queries and has not started a read or SQL query within the last 10
111
115
  # seconds. Idle transactions can be aborted by Cloud Spanner so that they
112
116
  # don't hold on to locks indefinitely. In that case, the commit will
113
- # fail with error +ABORTED+.
117
+ # fail with error `ABORTED`.
114
118
  #
115
119
  # If this behavior is undesirable, periodically executing a simple
116
- # SQL query in the transaction (e.g., +SELECT 1+) prevents the
120
+ # SQL query in the transaction (e.g., `SELECT 1`) prevents the
117
121
  # transaction from becoming idle.
118
122
  #
119
123
  # == Snapshot Read-Only Transactions
@@ -231,26 +235,92 @@ module Google
231
235
  # at read timestamps more than one hour in the past. This
232
236
  # restriction also applies to in-progress reads and/or SQL queries whose
233
237
  # timestamp become too old while executing. Reads and SQL queries with
234
- # too-old read timestamps fail with the error +FAILED_PRECONDITION+.
238
+ # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
239
+ #
240
+ # == Partitioned DML Transactions
241
+ #
242
+ # Partitioned DML transactions are used to execute DML statements with a
243
+ # different execution strategy that provides different, and often better,
244
+ # scalability properties for large, table-wide operations than DML in a
245
+ # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
246
+ # should prefer using ReadWrite transactions.
247
+ #
248
+ # Partitioned DML partitions the keyspace and runs the DML statement on each
249
+ # partition in separate, internal transactions. These transactions commit
250
+ # automatically when complete, and run independently from one another.
251
+ #
252
+ # To reduce lock contention, this execution strategy only acquires read locks
253
+ # on rows that match the WHERE clause of the statement. Additionally, the
254
+ # smaller per-partition transactions hold locks for less time.
255
+ #
256
+ # That said, Partitioned DML is not a drop-in replacement for standard DML used
257
+ # in ReadWrite transactions.
258
+ #
259
+ # * The DML statement must be fully-partitionable. Specifically, the statement
260
+ # must be expressible as the union of many statements which each access only
261
+ # a single row of the table.
262
+ #
263
+ # * The statement is not applied atomically to all rows of the table. Rather,
264
+ # the statement is applied atomically to partitions of the table, in
265
+ # independent transactions. Secondary index rows are updated atomically
266
+ # with the base table rows.
267
+ #
268
+ # * Partitioned DML does not guarantee exactly-once execution semantics
269
+ # against a partition. The statement will be applied at least once to each
270
+ # partition. It is strongly recommended that the DML statement should be
271
+ # idempotent to avoid unexpected results. For instance, it is potentially
272
+ # dangerous to run a statement such as
273
+ # `UPDATE table SET column = column + 1` as it could be run multiple times
274
+ # against some rows.
275
+ #
276
+ # * The partitions are committed automatically - there is no support for
277
+ # Commit or Rollback. If the call returns an error, or if the client issuing
278
+ # the ExecuteSql call dies, it is possible that some rows had the statement
279
+ # executed on them successfully. It is also possible that statement was
280
+ # never executed against other rows.
281
+ #
282
+ # * Partitioned DML transactions may only contain the execution of a single
283
+ # DML statement via ExecuteSql or ExecuteStreamingSql.
284
+ #
285
+ # * If any error is encountered during the execution of the partitioned DML
286
+ # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
287
+ # value that cannot be stored due to schema constraints), then the
288
+ # operation is stopped at that point and an error is returned. It is
289
+ # possible that at this point, some partitions have been committed (or even
290
+ # committed multiple times), and other partitions have not been run at all.
291
+ #
292
+ # Given the above, Partitioned DML is good fit for large, database-wide,
293
+ # operations that are idempotent, such as deleting old rows from a very large
294
+ # table.
235
295
  # @!attribute [rw] read_write
236
296
  # @return [Google::Spanner::V1::TransactionOptions::ReadWrite]
237
297
  # Transaction may write.
238
298
  #
239
299
  # Authorization to begin a read-write transaction requires
240
- # +spanner.databases.beginOrRollbackReadWriteTransaction+ permission
241
- # on the +session+ resource.
300
+ # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
301
+ # on the `session` resource.
302
+ # @!attribute [rw] partitioned_dml
303
+ # @return [Google::Spanner::V1::TransactionOptions::PartitionedDml]
304
+ # Partitioned DML transaction.
305
+ #
306
+ # Authorization to begin a Partitioned DML transaction requires
307
+ # `spanner.databases.beginPartitionedDmlTransaction` permission
308
+ # on the `session` resource.
242
309
  # @!attribute [rw] read_only
243
310
  # @return [Google::Spanner::V1::TransactionOptions::ReadOnly]
244
311
  # Transaction will not write.
245
312
  #
246
313
  # Authorization to begin a read-only transaction requires
247
- # +spanner.databases.beginReadOnlyTransaction+ permission
248
- # on the +session+ resource.
314
+ # `spanner.databases.beginReadOnlyTransaction` permission
315
+ # on the `session` resource.
249
316
  class TransactionOptions
250
317
  # Message type to initiate a read-write transaction. Currently this
251
318
  # transaction type has no options.
252
319
  class ReadWrite; end
253
320
 
321
+ # Message type to initiate a Partitioned DML transaction.
322
+ class PartitionedDml; end
323
+
254
324
  # Message type to initiate a read-only transaction.
255
325
  # @!attribute [rw] strong
256
326
  # @return [true, false]
@@ -258,7 +328,7 @@ module Google
258
328
  # are visible.
259
329
  # @!attribute [rw] min_read_timestamp
260
330
  # @return [Google::Protobuf::Timestamp]
261
- # Executes all reads at a timestamp >= +min_read_timestamp+.
331
+ # Executes all reads at a timestamp >= `min_read_timestamp`.
262
332
  #
263
333
  # This is useful for requesting fresher data than some previous
264
334
  # read, or data that is fresh enough to observe the effects of some
@@ -267,10 +337,10 @@ module Google
267
337
  # Note that this option can only be used in single-use transactions.
268
338
  #
269
339
  # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
270
- # Example: +"2014-10-02T15:01:23.045123456Z"+.
340
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
271
341
  # @!attribute [rw] max_staleness
272
342
  # @return [Google::Protobuf::Duration]
273
- # Read data at a timestamp >= +NOW - max_staleness+
343
+ # Read data at a timestamp >= `NOW - max_staleness`
274
344
  # seconds. Guarantees that all writes that have committed more
275
345
  # than the specified number of seconds ago are visible. Because
276
346
  # Cloud Spanner chooses the exact timestamp, this mode works even if
@@ -296,10 +366,10 @@ module Google
296
366
  # data.
297
367
  #
298
368
  # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
299
- # Example: +"2014-10-02T15:01:23.045123456Z"+.
369
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
300
370
  # @!attribute [rw] exact_staleness
301
371
  # @return [Google::Protobuf::Duration]
302
- # Executes all reads at a timestamp that is +exact_staleness+
372
+ # Executes all reads at a timestamp that is `exact_staleness`
303
373
  # old. The timestamp is chosen soon after the read is started.
304
374
  #
305
375
  # Guarantees that all writes that have committed more than the
@@ -309,7 +379,7 @@ module Google
309
379
  # timestamps.
310
380
  #
311
381
  # Useful for reading at nearby replicas without the distributed
312
- # timestamp negotiation overhead of +max_staleness+.
382
+ # timestamp negotiation overhead of `max_staleness`.
313
383
  # @!attribute [rw] return_read_timestamp
314
384
  # @return [true, false]
315
385
  # If true, the Cloud Spanner-selected read timestamp is included in
@@ -320,7 +390,7 @@ module Google
320
390
  # A transaction.
321
391
  # @!attribute [rw] id
322
392
  # @return [String]
323
- # +id+ may be used to identify the transaction in subsequent
393
+ # `id` may be used to identify the transaction in subsequent
324
394
  # {Google::Spanner::V1::Spanner::Read Read},
325
395
  # {Google::Spanner::V1::Spanner::ExecuteSql ExecuteSql},
326
396
  # {Google::Spanner::V1::Spanner::Commit Commit}, or
@@ -335,7 +405,7 @@ module Google
335
405
  # {Google::Spanner::V1::TransactionOptions::ReadOnly#return_read_timestamp TransactionOptions::ReadOnly#return_read_timestamp}.
336
406
  #
337
407
  # A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
338
- # Example: +"2014-10-02T15:01:23.045123456Z"+.
408
+ # Example: `"2014-10-02T15:01:23.045123456Z"`.
339
409
  class Transaction; end
340
410
 
341
411
  # This message is used to select the transaction in which a
@@ -16,22 +16,22 @@
16
16
  module Google
17
17
  module Spanner
18
18
  module V1
19
- # +Type+ indicates the type of a Cloud Spanner value, as might be stored in a
19
+ # `Type` indicates the type of a Cloud Spanner value, as might be stored in a
20
20
  # table cell or returned from an SQL query.
21
21
  # @!attribute [rw] code
22
22
  # @return [Google::Spanner::V1::TypeCode]
23
23
  # Required. The {Google::Spanner::V1::TypeCode TypeCode} for this type.
24
24
  # @!attribute [rw] array_element_type
25
25
  # @return [Google::Spanner::V1::Type]
26
- # If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::ARRAY ARRAY}, then +array_element_type+
26
+ # If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::ARRAY ARRAY}, then `array_element_type`
27
27
  # is the type of the array elements.
28
28
  # @!attribute [rw] struct_type
29
29
  # @return [Google::Spanner::V1::StructType]
30
- # If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::STRUCT STRUCT}, then +struct_type+
30
+ # If {Google::Spanner::V1::Type#code code} == {Google::Spanner::V1::TypeCode::STRUCT STRUCT}, then `struct_type`
31
31
  # provides type information for the struct's fields.
32
32
  class Type; end
33
33
 
34
- # +StructType+ defines the fields of a {Google::Spanner::V1::TypeCode::STRUCT STRUCT} type.
34
+ # `StructType` defines the fields of a {Google::Spanner::V1::TypeCode::STRUCT STRUCT} type.
35
35
  # @!attribute [rw] fields
36
36
  # @return [Array<Google::Spanner::V1::StructType::Field>]
37
37
  # The list of fields that make up this struct. Order is
@@ -39,17 +39,17 @@ module Google
39
39
  # lists, where the order of field values matches the order of
40
40
  # fields in the {Google::Spanner::V1::StructType StructType}. In turn, the order of fields
41
41
  # matches the order of columns in a read request, or the order of
42
- # fields in the +SELECT+ clause of a query.
42
+ # fields in the `SELECT` clause of a query.
43
43
  class StructType
44
44
  # Message representing a single field of a struct.
45
45
  # @!attribute [rw] name
46
46
  # @return [String]
47
47
  # The name of the field. For reads, this is the column name. For
48
- # SQL queries, it is the column alias (e.g., +"Word"+ in the
49
- # query +"SELECT 'hello' AS Word"+), or the column name (e.g.,
50
- # +"ColName"+ in the query +"SELECT ColName FROM Table"+). Some
48
+ # SQL queries, it is the column alias (e.g., `"Word"` in the
49
+ # query `"SELECT 'hello' AS Word"`), or the column name (e.g.,
50
+ # `"ColName"` in the query `"SELECT ColName FROM Table"`). Some
51
51
  # columns might have an empty name (e.g., !"SELECT
52
- # UPPER(ColName)"+). Note that a query result can contain
52
+ # UPPER(ColName)"`). Note that a query result can contain
53
53
  # multiple fields with the same name.
54
54
  # @!attribute [rw] type
55
55
  # @return [Google::Spanner::V1::Type]
@@ -57,52 +57,52 @@ module Google
57
57
  class Field; end
58
58
  end
59
59
 
60
- # +TypeCode+ is used as part of {Google::Spanner::V1::Type Type} to
60
+ # `TypeCode` is used as part of {Google::Spanner::V1::Type Type} to
61
61
  # indicate the type of a Cloud Spanner value.
62
62
  #
63
63
  # Each legal value of a type can be encoded to or decoded from a JSON
64
64
  # value, using the encodings described below. All Cloud Spanner values can
65
- # be +null+, regardless of type; +null+s are always encoded as a JSON
66
- # +null+.
65
+ # be `null`, regardless of type; `null`s are always encoded as a JSON
66
+ # `null`.
67
67
  module TypeCode
68
68
  # Not specified.
69
69
  TYPE_CODE_UNSPECIFIED = 0
70
70
 
71
- # Encoded as JSON +true+ or +false+.
71
+ # Encoded as JSON `true` or `false`.
72
72
  BOOL = 1
73
73
 
74
- # Encoded as +string+, in decimal format.
74
+ # Encoded as `string`, in decimal format.
75
75
  INT64 = 2
76
76
 
77
- # Encoded as +number+, or the strings +"NaN"+, +"Infinity"+, or
78
- # +"-Infinity"+.
77
+ # Encoded as `number`, or the strings `"NaN"`, `"Infinity"`, or
78
+ # `"-Infinity"`.
79
79
  FLOAT64 = 3
80
80
 
81
- # Encoded as +string+ in RFC 3339 timestamp format. The time zone
82
- # must be present, and must be +"Z"+.
81
+ # Encoded as `string` in RFC 3339 timestamp format. The time zone
82
+ # must be present, and must be `"Z"`.
83
83
  #
84
84
  # If the schema has the column option
85
- # +allow_commit_timestamp=true+, the placeholder string
86
- # +"spanner.commit_timestamp()"+ can be used to instruct the system
85
+ # `allow_commit_timestamp=true`, the placeholder string
86
+ # `"spanner.commit_timestamp()"` can be used to instruct the system
87
87
  # to insert the commit timestamp associated with the transaction
88
88
  # commit.
89
89
  TIMESTAMP = 4
90
90
 
91
- # Encoded as +string+ in RFC 3339 date format.
91
+ # Encoded as `string` in RFC 3339 date format.
92
92
  DATE = 5
93
93
 
94
- # Encoded as +string+.
94
+ # Encoded as `string`.
95
95
  STRING = 6
96
96
 
97
- # Encoded as a base64-encoded +string+, as described in RFC 4648,
97
+ # Encoded as a base64-encoded `string`, as described in RFC 4648,
98
98
  # section 4.
99
99
  BYTES = 7
100
100
 
101
- # Encoded as +list+, where the list elements are represented
101
+ # Encoded as `list`, where the list elements are represented
102
102
  # according to {Google::Spanner::V1::Type#array_element_type array_element_type}.
103
103
  ARRAY = 8
104
104
 
105
- # Encoded as +list+, where list element +i+ is represented according
105
+ # Encoded as `list`, where list element `i` is represented according
106
106
  # to [struct_type.fields[i]][google.spanner.v1.StructType.fields].
107
107
  STRUCT = 9
108
108
  end