google-cloud-spanner 1.2.0 → 1.3.1

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 (44) hide show
  1. checksums.yaml +4 -4
  2. data/lib/google-cloud-spanner.rb +25 -0
  3. data/lib/google/cloud/spanner.rb +71 -11
  4. data/lib/google/cloud/spanner/batch_client.rb +355 -0
  5. data/lib/google/cloud/spanner/batch_snapshot.rb +588 -0
  6. data/lib/google/cloud/spanner/client.rb +27 -20
  7. data/lib/google/cloud/spanner/commit.rb +6 -5
  8. data/lib/google/cloud/spanner/convert.rb +39 -0
  9. data/lib/google/cloud/spanner/credentials.rb +7 -7
  10. data/lib/google/cloud/spanner/data.rb +5 -5
  11. data/lib/google/cloud/spanner/database.rb +13 -7
  12. data/lib/google/cloud/spanner/database/job.rb +7 -2
  13. data/lib/google/cloud/spanner/database/list.rb +1 -1
  14. data/lib/google/cloud/spanner/fields.rb +16 -12
  15. data/lib/google/cloud/spanner/instance.rb +25 -13
  16. data/lib/google/cloud/spanner/instance/config.rb +2 -2
  17. data/lib/google/cloud/spanner/instance/config/list.rb +1 -1
  18. data/lib/google/cloud/spanner/instance/job.rb +7 -2
  19. data/lib/google/cloud/spanner/instance/list.rb +1 -1
  20. data/lib/google/cloud/spanner/partition.rb +208 -0
  21. data/lib/google/cloud/spanner/pool.rb +6 -6
  22. data/lib/google/cloud/spanner/project.rb +59 -16
  23. data/lib/google/cloud/spanner/results.rb +12 -5
  24. data/lib/google/cloud/spanner/service.rb +85 -61
  25. data/lib/google/cloud/spanner/session.rb +45 -9
  26. data/lib/google/cloud/spanner/snapshot.rb +10 -2
  27. data/lib/google/cloud/spanner/status.rb +6 -5
  28. data/lib/google/cloud/spanner/transaction.rb +11 -3
  29. data/lib/google/cloud/spanner/v1/doc/google/protobuf/duration.rb +1 -1
  30. data/lib/google/cloud/spanner/v1/doc/google/protobuf/struct.rb +1 -1
  31. data/lib/google/cloud/spanner/v1/doc/google/protobuf/timestamp.rb +1 -1
  32. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/keys.rb +1 -1
  33. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/mutation.rb +1 -1
  34. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/query_plan.rb +1 -1
  35. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/result_set.rb +1 -1
  36. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/spanner.rb +138 -6
  37. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/transaction.rb +1 -1
  38. data/lib/google/cloud/spanner/v1/doc/overview.rb +6 -5
  39. data/lib/google/cloud/spanner/v1/spanner_client.rb +257 -33
  40. data/lib/google/cloud/spanner/v1/spanner_client_config.json +10 -0
  41. data/lib/google/cloud/spanner/version.rb +1 -1
  42. data/lib/google/spanner/v1/spanner_pb.rb +35 -0
  43. data/lib/google/spanner/v1/spanner_services_pb.rb +20 -2
  44. metadata +12 -9
@@ -14,6 +14,7 @@
14
14
 
15
15
 
16
16
  require "google/cloud/spanner/errors"
17
+ require "google/cloud/spanner/convert"
17
18
  require "google/cloud/spanner/results"
18
19
  require "google/cloud/spanner/commit"
19
20
 
@@ -178,10 +179,13 @@ module Google
178
179
  #
179
180
  def execute sql, params: nil, types: nil
180
181
  ensure_session!
182
+
183
+ params, types = Convert.to_input_params_and_types params, types
184
+
181
185
  session.execute sql, params: params, types: types,
182
186
  transaction: tx_selector
183
187
  end
184
- alias_method :query, :execute
188
+ alias query execute
185
189
 
186
190
  ##
187
191
  # Read rows from a database table, as a simple alternative to
@@ -219,6 +223,10 @@ module Google
219
223
  #
220
224
  def read table, columns, keys: nil, index: nil, limit: nil
221
225
  ensure_session!
226
+
227
+ columns = Array(columns).map(&:to_s)
228
+ keys = Convert.to_key_set keys
229
+
222
230
  session.read table, columns, keys: keys, index: index, limit: limit,
223
231
  transaction: tx_selector
224
232
  end
@@ -268,7 +276,7 @@ module Google
268
276
  ensure_session!
269
277
  @commit.upsert table, rows
270
278
  end
271
- alias_method :save, :upsert
279
+ alias save upsert
272
280
 
273
281
  ##
274
282
  # Inserts new rows in a table. If any of the rows already exist, the
@@ -548,7 +556,7 @@ module Google
548
556
  # @private Raise an error unless an active connection to the service is
549
557
  # available.
550
558
  def ensure_session!
551
- fail "Must have active connection to service" unless session
559
+ raise "Must have active connection to service" unless session
552
560
  end
553
561
 
554
562
  def service
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -19,7 +19,7 @@ module Google
19
19
  #
20
20
  # | Class | Description |
21
21
  # | ----- | ----------- |
22
- # | [SpannerClient][] | Cloud Spanner is a managed, mission-critical, globally consistent and scalable relational database service. |
22
+ # | [SpannerClient][] | Cloud Spanner API |
23
23
  # | [Data Types][] | Data types for Google::Cloud::Spanner::V1 |
24
24
  #
25
25
  # [SpannerClient]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-spanner/latest/google/spanner/v1/spannerclient
@@ -159,7 +159,14 @@ module Google
159
159
  # @!attribute [rw] query_mode
160
160
  # @return [Google::Spanner::V1::ExecuteSqlRequest::QueryMode]
161
161
  # Used to control the amount of debugging information returned in
162
- # {Google::Spanner::V1::ResultSetStats ResultSetStats}.
162
+ # {Google::Spanner::V1::ResultSetStats ResultSetStats}. If {Google::Spanner::V1::ExecuteSqlRequest#partition_token partition_token} is set, {Google::Spanner::V1::ExecuteSqlRequest#query_mode query_mode} can only
163
+ # be set to {Google::Spanner::V1::ExecuteSqlRequest::QueryMode::NORMAL QueryMode::NORMAL}.
164
+ # @!attribute [rw] partition_token
165
+ # @return [String]
166
+ # If present, results will be restricted to the specified partition
167
+ # previously created using PartitionQuery(). There must be an exact
168
+ # match for the values of fields common to this message and the
169
+ # PartitionQueryRequest message used to create this partition_token.
163
170
  class ExecuteSqlRequest
164
171
  # Mode in which the query must be processed.
165
172
  module QueryMode
@@ -177,6 +184,122 @@ module Google
177
184
  end
178
185
  end
179
186
 
187
+ # Options for a PartitionQueryRequest and
188
+ # PartitionReadRequest.
189
+ # @!attribute [rw] partition_size_bytes
190
+ # @return [Integer]
191
+ # The desired data size for each partition generated. The default for this
192
+ # option is currently 1 GiB. This is only a hint. The actual size of each
193
+ # partition may be smaller or larger than this size request.
194
+ # @!attribute [rw] max_partitions
195
+ # @return [Integer]
196
+ # The desired maximum number of partitions to return. For example, this may
197
+ # be set to the number of workers available. The default for this option
198
+ # is currently 10,000. The maximum value is currently 200,000. This is only
199
+ # a hint. The actual number of partitions returned may be smaller or larger
200
+ # than this maximum count request.
201
+ class PartitionOptions; end
202
+
203
+ # The request for {Google::Spanner::V1::Spanner::PartitionQuery PartitionQuery}
204
+ # @!attribute [rw] session
205
+ # @return [String]
206
+ # Required. The session used to create the partitions.
207
+ # @!attribute [rw] transaction
208
+ # @return [Google::Spanner::V1::TransactionSelector]
209
+ # Read only snapshot transactions are supported, read/write and single use
210
+ # transactions are not.
211
+ # @!attribute [rw] sql
212
+ # @return [String]
213
+ # The query request to generate partitions for. The request will fail if
214
+ # the query is not root partitionable. The query plan of a root
215
+ # partitionable query has a single distributed union operator. A distributed
216
+ # union operator conceptually divides one or more tables into multiple
217
+ # splits, remotely evaluates a subquery independently on each split, and
218
+ # then unions all results.
219
+ # @!attribute [rw] params
220
+ # @return [Google::Protobuf::Struct]
221
+ # The SQL query string can contain parameter placeholders. A parameter
222
+ # placeholder consists of +'@'+ followed by the parameter
223
+ # name. Parameter names consist of any combination of letters,
224
+ # numbers, and underscores.
225
+ #
226
+ # Parameters can appear anywhere that a literal value is expected. The same
227
+ # parameter name can be used more than once, for example:
228
+ # +"WHERE id > @msg_id AND id < @msg_id + 100"+
229
+ #
230
+ # It is an error to execute an SQL query with unbound parameters.
231
+ #
232
+ # Parameter values are specified using +params+, which is a JSON
233
+ # object whose keys are parameter names, and whose values are the
234
+ # corresponding parameter values.
235
+ # @!attribute [rw] param_types
236
+ # @return [Hash{String => Google::Spanner::V1::Type}]
237
+ # It is not always possible for Cloud Spanner to infer the right SQL type
238
+ # from a JSON value. For example, values of type +BYTES+ and values
239
+ # of type +STRING+ both appear in {Google::Spanner::V1::PartitionQueryRequest#params params} as JSON strings.
240
+ #
241
+ # In these cases, +param_types+ can be used to specify the exact
242
+ # SQL type for some or all of the SQL query parameters. See the
243
+ # definition of {Google::Spanner::V1::Type Type} for more information
244
+ # about SQL types.
245
+ # @!attribute [rw] partition_options
246
+ # @return [Google::Spanner::V1::PartitionOptions]
247
+ # Additional options that affect how many partitions are created.
248
+ class PartitionQueryRequest; end
249
+
250
+ # The request for {Google::Spanner::V1::Spanner::PartitionRead PartitionRead}
251
+ # @!attribute [rw] session
252
+ # @return [String]
253
+ # Required. The session used to create the partitions.
254
+ # @!attribute [rw] transaction
255
+ # @return [Google::Spanner::V1::TransactionSelector]
256
+ # Read only snapshot transactions are supported, read/write and single use
257
+ # transactions are not.
258
+ # @!attribute [rw] table
259
+ # @return [String]
260
+ # Required. The name of the table in the database to be read.
261
+ # @!attribute [rw] index
262
+ # @return [String]
263
+ # If non-empty, the name of an index on {Google::Spanner::V1::PartitionReadRequest#table table}. This index is
264
+ # used instead of the table primary key when interpreting {Google::Spanner::V1::PartitionReadRequest#key_set key_set}
265
+ # and sorting result rows. See {Google::Spanner::V1::PartitionReadRequest#key_set key_set} for further information.
266
+ # @!attribute [rw] columns
267
+ # @return [Array<String>]
268
+ # The columns of {Google::Spanner::V1::PartitionReadRequest#table table} to be returned for each row matching
269
+ # this request.
270
+ # @!attribute [rw] key_set
271
+ # @return [Google::Spanner::V1::KeySet]
272
+ # Required. +key_set+ identifies the rows to be yielded. +key_set+ names the
273
+ # primary keys of the rows in {Google::Spanner::V1::PartitionReadRequest#table table} to be yielded, unless {Google::Spanner::V1::PartitionReadRequest#index index}
274
+ # is present. If {Google::Spanner::V1::PartitionReadRequest#index index} is present, then {Google::Spanner::V1::PartitionReadRequest#key_set key_set} instead names
275
+ # index keys in {Google::Spanner::V1::PartitionReadRequest#index index}.
276
+ #
277
+ # It is not an error for the +key_set+ to name rows that do not
278
+ # exist in the database. Read yields nothing for nonexistent rows.
279
+ # @!attribute [rw] partition_options
280
+ # @return [Google::Spanner::V1::PartitionOptions]
281
+ # Additional options that affect how many partitions are created.
282
+ class PartitionReadRequest; end
283
+
284
+ # Information returned for each partition returned in a
285
+ # PartitionResponse.
286
+ # @!attribute [rw] partition_token
287
+ # @return [String]
288
+ # This token can be passed to Read, StreamingRead, ExecuteSql, or
289
+ # ExecuteStreamingSql requests to restrict the results to those identified by
290
+ # this partition token.
291
+ class Partition; end
292
+
293
+ # The response for {Google::Spanner::V1::Spanner::PartitionQuery PartitionQuery}
294
+ # or {Google::Spanner::V1::Spanner::PartitionRead PartitionRead}
295
+ # @!attribute [rw] partitions
296
+ # @return [Array<Google::Spanner::V1::Partition>]
297
+ # Partitions created by this request.
298
+ # @!attribute [rw] transaction
299
+ # @return [Google::Spanner::V1::Transaction]
300
+ # Transaction created by this request.
301
+ class PartitionResponse; end
302
+
180
303
  # The request for {Google::Spanner::V1::Spanner::Read Read} and
181
304
  # {Google::Spanner::V1::Spanner::StreamingRead StreamingRead}.
182
305
  # @!attribute [rw] session
@@ -205,15 +328,18 @@ module Google
205
328
  # is present. If {Google::Spanner::V1::ReadRequest#index index} is present, then {Google::Spanner::V1::ReadRequest#key_set key_set} instead names
206
329
  # index keys in {Google::Spanner::V1::ReadRequest#index index}.
207
330
  #
208
- # Rows are yielded in table primary key order (if {Google::Spanner::V1::ReadRequest#index index} is empty)
209
- # or index key order (if {Google::Spanner::V1::ReadRequest#index index} is non-empty).
331
+ # If the {Google::Spanner::V1::ReadRequest#partition_token partition_token} field is empty, rows are yielded
332
+ # in table primary key order (if {Google::Spanner::V1::ReadRequest#index index} is empty) or index key order
333
+ # (if {Google::Spanner::V1::ReadRequest#index index} is non-empty). If the {Google::Spanner::V1::ReadRequest#partition_token partition_token} field is not
334
+ # empty, rows will be yielded in an unspecified order.
210
335
  #
211
336
  # It is not an error for the +key_set+ to name rows that do not
212
337
  # exist in the database. Read yields nothing for nonexistent rows.
213
338
  # @!attribute [rw] limit
214
339
  # @return [Integer]
215
340
  # If greater than zero, only the first +limit+ rows are yielded. If +limit+
216
- # is zero, the default is no limit.
341
+ # is zero, the default is no limit. A limit cannot be specified if
342
+ # +partition_token+ is set.
217
343
  # @!attribute [rw] resume_token
218
344
  # @return [String]
219
345
  # If this request is resuming a previously interrupted read,
@@ -222,6 +348,12 @@ module Google
222
348
  # enables the new read to resume where the last read left off. The
223
349
  # rest of the request parameters must exactly match the request
224
350
  # that yielded this token.
351
+ # @!attribute [rw] partition_token
352
+ # @return [String]
353
+ # If present, results will be restricted to the specified partition
354
+ # previously created using PartitionRead(). There must be an exact
355
+ # match for the values of fields common to this message and the
356
+ # PartitionReadRequest message used to create this partition_token.
225
357
  class ReadRequest; end
226
358
 
227
359
  # The request for {Google::Spanner::V1::Spanner::BeginTransaction BeginTransaction}.
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -20,8 +20,8 @@ module Google
20
20
  # # Ruby Client for Cloud Spanner API ([Alpha](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
21
21
  #
22
22
  # [Cloud Spanner API][Product Documentation]:
23
- # Cloud Spanner is a managed, mission-critical, globally consistent and scalable
24
- # relational database service.
23
+ # Cloud Spanner is a managed, mission-critical, globally consistent and
24
+ # scalable relational database service.
25
25
  # - [Product Documentation][]
26
26
  #
27
27
  # ## Quick Start
@@ -29,8 +29,9 @@ module Google
29
29
  # steps:
30
30
  #
31
31
  # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
32
- # 2. [Enable the Cloud Spanner API.](https://console.cloud.google.com/apis/api/spanner)
33
- # 3. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
32
+ # 2. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
33
+ # 3. [Enable the Cloud Spanner API.](https://console.cloud.google.com/apis/api/spanner)
34
+ # 4. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
34
35
  #
35
36
  # ### Installation
36
37
  # ```
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -18,9 +18,6 @@
18
18
  # and updates to that file get reflected here through a refresh process.
19
19
  # For the short term, the refresh process will only be runnable by Google
20
20
  # engineers.
21
- #
22
- # The only allowed edits are to method and file documentation. A 3-way
23
- # merge preserves those additions if the generated source changes.
24
21
 
25
22
  require "json"
26
23
  require "pathname"
@@ -65,9 +62,11 @@ module Google
65
62
  # this service.
66
63
  ALL_SCOPES = [
67
64
  "https://www.googleapis.com/auth/cloud-platform",
65
+ "https://www.googleapis.com/auth/spanner.admin",
68
66
  "https://www.googleapis.com/auth/spanner.data"
69
67
  ].freeze
70
68
 
69
+
71
70
  DATABASE_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
72
71
  "projects/{project}/instances/{instance}/databases/{database}"
73
72
  )
@@ -133,11 +132,6 @@ module Google
133
132
  # @param timeout [Numeric]
134
133
  # The default timeout, in seconds, for calls made through this client.
135
134
  def initialize \
136
- service_path: SERVICE_ADDRESS,
137
- port: DEFAULT_SERVICE_PORT,
138
- channel: nil,
139
- chan_creds: nil,
140
- updater_proc: nil,
141
135
  credentials: nil,
142
136
  scopes: ALL_SCOPES,
143
137
  client_config: {},
@@ -150,17 +144,6 @@ module Google
150
144
  require "google/gax/grpc"
151
145
  require "google/spanner/v1/spanner_services_pb"
152
146
 
153
- if channel || chan_creds || updater_proc
154
- warn "The `channel`, `chan_creds`, and `updater_proc` parameters will be removed " \
155
- "on 2017/09/08"
156
- credentials ||= channel
157
- credentials ||= chan_creds
158
- credentials ||= updater_proc
159
- end
160
- if service_path != SERVICE_ADDRESS || port != DEFAULT_SERVICE_PORT
161
- warn "`service_path` and `port` parameters are deprecated and will be removed"
162
- end
163
-
164
147
  credentials ||= Google::Cloud::Spanner::Credentials.default
165
148
 
166
149
  if credentials.is_a?(String) || credentials.is_a?(Hash)
@@ -179,9 +162,11 @@ module Google
179
162
  updater_proc = credentials.updater_proc
180
163
  end
181
164
 
165
+ package_version = Gem.loaded_specs['google-cloud-spanner'].version.version
166
+
182
167
  google_api_client = "gl-ruby/#{RUBY_VERSION}"
183
168
  google_api_client << " #{lib_name}/#{lib_version}" if lib_name
184
- google_api_client << " gapic/0.1.0 gax/#{Google::Gax::VERSION}"
169
+ google_api_client << " gapic/#{package_version} gax/#{Google::Gax::VERSION}"
185
170
  google_api_client << " grpc/#{GRPC::VERSION}"
186
171
  google_api_client.freeze
187
172
 
@@ -201,6 +186,10 @@ module Google
201
186
  kwargs: headers
202
187
  )
203
188
  end
189
+
190
+ # Allow overriding the service path/port in subclasses.
191
+ service_path = self.class::SERVICE_ADDRESS
192
+ port = self.class::DEFAULT_SERVICE_PORT
204
193
  @spanner_stub = Google::Gax::Grpc.create_stub(
205
194
  service_path,
206
195
  port,
@@ -255,6 +244,14 @@ module Google
255
244
  @spanner_stub.method(:rollback),
256
245
  defaults["rollback"]
257
246
  )
247
+ @partition_query = Google::Gax.create_api_call(
248
+ @spanner_stub.method(:partition_query),
249
+ defaults["partition_query"]
250
+ )
251
+ @partition_read = Google::Gax.create_api_call(
252
+ @spanner_stub.method(:partition_read),
253
+ defaults["partition_read"]
254
+ )
258
255
  end
259
256
 
260
257
  # Service calls
@@ -484,7 +481,13 @@ module Google
484
481
  # request that yielded this token.
485
482
  # @param query_mode [Google::Spanner::V1::ExecuteSqlRequest::QueryMode]
486
483
  # Used to control the amount of debugging information returned in
487
- # {Google::Spanner::V1::ResultSetStats ResultSetStats}.
484
+ # {Google::Spanner::V1::ResultSetStats ResultSetStats}. If {Google::Spanner::V1::ExecuteSqlRequest#partition_token partition_token} is set, {Google::Spanner::V1::ExecuteSqlRequest#query_mode query_mode} can only
485
+ # be set to {Google::Spanner::V1::ExecuteSqlRequest::QueryMode::NORMAL QueryMode::NORMAL}.
486
+ # @param partition_token [String]
487
+ # If present, results will be restricted to the specified partition
488
+ # previously created using PartitionQuery(). There must be an exact
489
+ # match for the values of fields common to this message and the
490
+ # PartitionQueryRequest message used to create this partition_token.
488
491
  # @param options [Google::Gax::CallOptions]
489
492
  # Overrides the default settings for this call, e.g, timeout,
490
493
  # retries, etc.
@@ -495,6 +498,8 @@ module Google
495
498
  #
496
499
  # spanner_client = Google::Cloud::Spanner::V1.new
497
500
  # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]")
501
+ #
502
+ # # TODO: Initialize +sql+:
498
503
  # sql = ''
499
504
  # response = spanner_client.execute_sql(formatted_session, sql)
500
505
 
@@ -506,6 +511,7 @@ module Google
506
511
  param_types: nil,
507
512
  resume_token: nil,
508
513
  query_mode: nil,
514
+ partition_token: nil,
509
515
  options: nil
510
516
  req = {
511
517
  session: session,
@@ -514,7 +520,8 @@ module Google
514
520
  params: params,
515
521
  param_types: param_types,
516
522
  resume_token: resume_token,
517
- query_mode: query_mode
523
+ query_mode: query_mode,
524
+ partition_token: partition_token
518
525
  }.delete_if { |_, v| v.nil? }
519
526
  req = Google::Gax::to_proto(req, Google::Spanner::V1::ExecuteSqlRequest)
520
527
  @execute_sql.call(req, options)
@@ -572,7 +579,13 @@ module Google
572
579
  # request that yielded this token.
573
580
  # @param query_mode [Google::Spanner::V1::ExecuteSqlRequest::QueryMode]
574
581
  # Used to control the amount of debugging information returned in
575
- # {Google::Spanner::V1::ResultSetStats ResultSetStats}.
582
+ # {Google::Spanner::V1::ResultSetStats ResultSetStats}. If {Google::Spanner::V1::ExecuteSqlRequest#partition_token partition_token} is set, {Google::Spanner::V1::ExecuteSqlRequest#query_mode query_mode} can only
583
+ # be set to {Google::Spanner::V1::ExecuteSqlRequest::QueryMode::NORMAL QueryMode::NORMAL}.
584
+ # @param partition_token [String]
585
+ # If present, results will be restricted to the specified partition
586
+ # previously created using PartitionQuery(). There must be an exact
587
+ # match for the values of fields common to this message and the
588
+ # PartitionQueryRequest message used to create this partition_token.
576
589
  # @param options [Google::Gax::CallOptions]
577
590
  # Overrides the default settings for this call, e.g, timeout,
578
591
  # retries, etc.
@@ -585,6 +598,8 @@ module Google
585
598
  #
586
599
  # spanner_client = Google::Cloud::Spanner::V1.new
587
600
  # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]")
601
+ #
602
+ # # TODO: Initialize +sql+:
588
603
  # sql = ''
589
604
  # spanner_client.execute_streaming_sql(formatted_session, sql).each do |element|
590
605
  # # Process element.
@@ -598,6 +613,7 @@ module Google
598
613
  param_types: nil,
599
614
  resume_token: nil,
600
615
  query_mode: nil,
616
+ partition_token: nil,
601
617
  options: nil
602
618
  req = {
603
619
  session: session,
@@ -606,7 +622,8 @@ module Google
606
622
  params: params,
607
623
  param_types: param_types,
608
624
  resume_token: resume_token,
609
- query_mode: query_mode
625
+ query_mode: query_mode,
626
+ partition_token: partition_token
610
627
  }.delete_if { |_, v| v.nil? }
611
628
  req = Google::Gax::to_proto(req, Google::Spanner::V1::ExecuteSqlRequest)
612
629
  @execute_streaming_sql.call(req, options)
@@ -639,8 +656,10 @@ module Google
639
656
  # is present. If {Google::Spanner::V1::ReadRequest#index index} is present, then {Google::Spanner::V1::ReadRequest#key_set key_set} instead names
640
657
  # index keys in {Google::Spanner::V1::ReadRequest#index index}.
641
658
  #
642
- # Rows are yielded in table primary key order (if {Google::Spanner::V1::ReadRequest#index index} is empty)
643
- # or index key order (if {Google::Spanner::V1::ReadRequest#index index} is non-empty).
659
+ # If the {Google::Spanner::V1::ReadRequest#partition_token partition_token} field is empty, rows are yielded
660
+ # in table primary key order (if {Google::Spanner::V1::ReadRequest#index index} is empty) or index key order
661
+ # (if {Google::Spanner::V1::ReadRequest#index index} is non-empty). If the {Google::Spanner::V1::ReadRequest#partition_token partition_token} field is not
662
+ # empty, rows will be yielded in an unspecified order.
644
663
  #
645
664
  # It is not an error for the +key_set+ to name rows that do not
646
665
  # exist in the database. Read yields nothing for nonexistent rows.
@@ -657,7 +676,8 @@ module Google
657
676
  # and sorting result rows. See {Google::Spanner::V1::ReadRequest#key_set key_set} for further information.
658
677
  # @param limit [Integer]
659
678
  # If greater than zero, only the first +limit+ rows are yielded. If +limit+
660
- # is zero, the default is no limit.
679
+ # is zero, the default is no limit. A limit cannot be specified if
680
+ # +partition_token+ is set.
661
681
  # @param resume_token [String]
662
682
  # If this request is resuming a previously interrupted read,
663
683
  # +resume_token+ should be copied from the last
@@ -665,6 +685,11 @@ module Google
665
685
  # enables the new read to resume where the last read left off. The
666
686
  # rest of the request parameters must exactly match the request
667
687
  # that yielded this token.
688
+ # @param partition_token [String]
689
+ # If present, results will be restricted to the specified partition
690
+ # previously created using PartitionRead(). There must be an exact
691
+ # match for the values of fields common to this message and the
692
+ # PartitionReadRequest message used to create this partition_token.
668
693
  # @param options [Google::Gax::CallOptions]
669
694
  # Overrides the default settings for this call, e.g, timeout,
670
695
  # retries, etc.
@@ -675,8 +700,14 @@ module Google
675
700
  #
676
701
  # spanner_client = Google::Cloud::Spanner::V1.new
677
702
  # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]")
703
+ #
704
+ # # TODO: Initialize +table+:
678
705
  # table = ''
706
+ #
707
+ # # TODO: Initialize +columns+:
679
708
  # columns = []
709
+ #
710
+ # # TODO: Initialize +key_set+:
680
711
  # key_set = {}
681
712
  # response = spanner_client.read(formatted_session, table, columns, key_set)
682
713
 
@@ -689,6 +720,7 @@ module Google
689
720
  index: nil,
690
721
  limit: nil,
691
722
  resume_token: nil,
723
+ partition_token: nil,
692
724
  options: nil
693
725
  req = {
694
726
  session: session,
@@ -698,7 +730,8 @@ module Google
698
730
  transaction: transaction,
699
731
  index: index,
700
732
  limit: limit,
701
- resume_token: resume_token
733
+ resume_token: resume_token,
734
+ partition_token: partition_token
702
735
  }.delete_if { |_, v| v.nil? }
703
736
  req = Google::Gax::to_proto(req, Google::Spanner::V1::ReadRequest)
704
737
  @read.call(req, options)
@@ -723,8 +756,10 @@ module Google
723
756
  # is present. If {Google::Spanner::V1::ReadRequest#index index} is present, then {Google::Spanner::V1::ReadRequest#key_set key_set} instead names
724
757
  # index keys in {Google::Spanner::V1::ReadRequest#index index}.
725
758
  #
726
- # Rows are yielded in table primary key order (if {Google::Spanner::V1::ReadRequest#index index} is empty)
727
- # or index key order (if {Google::Spanner::V1::ReadRequest#index index} is non-empty).
759
+ # If the {Google::Spanner::V1::ReadRequest#partition_token partition_token} field is empty, rows are yielded
760
+ # in table primary key order (if {Google::Spanner::V1::ReadRequest#index index} is empty) or index key order
761
+ # (if {Google::Spanner::V1::ReadRequest#index index} is non-empty). If the {Google::Spanner::V1::ReadRequest#partition_token partition_token} field is not
762
+ # empty, rows will be yielded in an unspecified order.
728
763
  #
729
764
  # It is not an error for the +key_set+ to name rows that do not
730
765
  # exist in the database. Read yields nothing for nonexistent rows.
@@ -741,7 +776,8 @@ module Google
741
776
  # and sorting result rows. See {Google::Spanner::V1::ReadRequest#key_set key_set} for further information.
742
777
  # @param limit [Integer]
743
778
  # If greater than zero, only the first +limit+ rows are yielded. If +limit+
744
- # is zero, the default is no limit.
779
+ # is zero, the default is no limit. A limit cannot be specified if
780
+ # +partition_token+ is set.
745
781
  # @param resume_token [String]
746
782
  # If this request is resuming a previously interrupted read,
747
783
  # +resume_token+ should be copied from the last
@@ -749,6 +785,11 @@ module Google
749
785
  # enables the new read to resume where the last read left off. The
750
786
  # rest of the request parameters must exactly match the request
751
787
  # that yielded this token.
788
+ # @param partition_token [String]
789
+ # If present, results will be restricted to the specified partition
790
+ # previously created using PartitionRead(). There must be an exact
791
+ # match for the values of fields common to this message and the
792
+ # PartitionReadRequest message used to create this partition_token.
752
793
  # @param options [Google::Gax::CallOptions]
753
794
  # Overrides the default settings for this call, e.g, timeout,
754
795
  # retries, etc.
@@ -761,8 +802,14 @@ module Google
761
802
  #
762
803
  # spanner_client = Google::Cloud::Spanner::V1.new
763
804
  # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]")
805
+ #
806
+ # # TODO: Initialize +table+:
764
807
  # table = ''
808
+ #
809
+ # # TODO: Initialize +columns+:
765
810
  # columns = []
811
+ #
812
+ # # TODO: Initialize +key_set+:
766
813
  # key_set = {}
767
814
  # spanner_client.streaming_read(formatted_session, table, columns, key_set).each do |element|
768
815
  # # Process element.
@@ -777,6 +824,7 @@ module Google
777
824
  index: nil,
778
825
  limit: nil,
779
826
  resume_token: nil,
827
+ partition_token: nil,
780
828
  options: nil
781
829
  req = {
782
830
  session: session,
@@ -786,7 +834,8 @@ module Google
786
834
  transaction: transaction,
787
835
  index: index,
788
836
  limit: limit,
789
- resume_token: resume_token
837
+ resume_token: resume_token,
838
+ partition_token: partition_token
790
839
  }.delete_if { |_, v| v.nil? }
791
840
  req = Google::Gax::to_proto(req, Google::Spanner::V1::ReadRequest)
792
841
  @streaming_read.call(req, options)
@@ -813,6 +862,8 @@ module Google
813
862
  #
814
863
  # spanner_client = Google::Cloud::Spanner::V1.new
815
864
  # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]")
865
+ #
866
+ # # TODO: Initialize +options_+:
816
867
  # options_ = {}
817
868
  # response = spanner_client.begin_transaction(formatted_session, options_)
818
869
 
@@ -869,6 +920,8 @@ module Google
869
920
  #
870
921
  # spanner_client = Google::Cloud::Spanner::V1.new
871
922
  # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]")
923
+ #
924
+ # # TODO: Initialize +mutations+:
872
925
  # mutations = []
873
926
  # response = spanner_client.commit(formatted_session, mutations)
874
927
 
@@ -910,6 +963,8 @@ module Google
910
963
  #
911
964
  # spanner_client = Google::Cloud::Spanner::V1.new
912
965
  # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]")
966
+ #
967
+ # # TODO: Initialize +transaction_id+:
913
968
  # transaction_id = ''
914
969
  # spanner_client.rollback(formatted_session, transaction_id)
915
970
 
@@ -925,6 +980,175 @@ module Google
925
980
  @rollback.call(req, options)
926
981
  nil
927
982
  end
983
+
984
+ # Creates a set of partition tokens that can be used to execute a query
985
+ # operation in parallel. Each of the returned partition tokens can be used
986
+ # by {Google::Spanner::V1::Spanner::ExecuteStreamingSql ExecuteStreamingSql} to specify a subset
987
+ # of the query result to read. The same session and read-only transaction
988
+ # must be used by the PartitionQueryRequest used to create the
989
+ # partition tokens and the ExecuteSqlRequests that use the partition tokens.
990
+ # Partition tokens become invalid when the session used to create them
991
+ # is deleted or begins a new transaction.
992
+ #
993
+ # @param session [String]
994
+ # Required. The session used to create the partitions.
995
+ # @param sql [String]
996
+ # The query request to generate partitions for. The request will fail if
997
+ # the query is not root partitionable. The query plan of a root
998
+ # partitionable query has a single distributed union operator. A distributed
999
+ # union operator conceptually divides one or more tables into multiple
1000
+ # splits, remotely evaluates a subquery independently on each split, and
1001
+ # then unions all results.
1002
+ # @param transaction [Google::Spanner::V1::TransactionSelector | Hash]
1003
+ # Read only snapshot transactions are supported, read/write and single use
1004
+ # transactions are not.
1005
+ # A hash of the same form as `Google::Spanner::V1::TransactionSelector`
1006
+ # can also be provided.
1007
+ # @param params [Google::Protobuf::Struct | Hash]
1008
+ # The SQL query string can contain parameter placeholders. A parameter
1009
+ # placeholder consists of +'@'+ followed by the parameter
1010
+ # name. Parameter names consist of any combination of letters,
1011
+ # numbers, and underscores.
1012
+ #
1013
+ # Parameters can appear anywhere that a literal value is expected. The same
1014
+ # parameter name can be used more than once, for example:
1015
+ # +"WHERE id > @msg_id AND id < @msg_id + 100"+
1016
+ #
1017
+ # It is an error to execute an SQL query with unbound parameters.
1018
+ #
1019
+ # Parameter values are specified using +params+, which is a JSON
1020
+ # object whose keys are parameter names, and whose values are the
1021
+ # corresponding parameter values.
1022
+ # A hash of the same form as `Google::Protobuf::Struct`
1023
+ # can also be provided.
1024
+ # @param param_types [Hash{String => Google::Spanner::V1::Type | Hash}]
1025
+ # It is not always possible for Cloud Spanner to infer the right SQL type
1026
+ # from a JSON value. For example, values of type +BYTES+ and values
1027
+ # of type +STRING+ both appear in {Google::Spanner::V1::PartitionQueryRequest#params params} as JSON strings.
1028
+ #
1029
+ # In these cases, +param_types+ can be used to specify the exact
1030
+ # SQL type for some or all of the SQL query parameters. See the
1031
+ # definition of {Google::Spanner::V1::Type Type} for more information
1032
+ # about SQL types.
1033
+ # A hash of the same form as `Google::Spanner::V1::Type`
1034
+ # can also be provided.
1035
+ # @param partition_options [Google::Spanner::V1::PartitionOptions | Hash]
1036
+ # Additional options that affect how many partitions are created.
1037
+ # A hash of the same form as `Google::Spanner::V1::PartitionOptions`
1038
+ # can also be provided.
1039
+ # @param options [Google::Gax::CallOptions]
1040
+ # Overrides the default settings for this call, e.g, timeout,
1041
+ # retries, etc.
1042
+ # @return [Google::Spanner::V1::PartitionResponse]
1043
+ # @raise [Google::Gax::GaxError] if the RPC is aborted.
1044
+ # @example
1045
+ # require "google/cloud/spanner/v1"
1046
+ #
1047
+ # spanner_client = Google::Cloud::Spanner::V1.new
1048
+ # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]")
1049
+ #
1050
+ # # TODO: Initialize +sql+:
1051
+ # sql = ''
1052
+ # response = spanner_client.partition_query(formatted_session, sql)
1053
+
1054
+ def partition_query \
1055
+ session,
1056
+ sql,
1057
+ transaction: nil,
1058
+ params: nil,
1059
+ param_types: nil,
1060
+ partition_options: nil,
1061
+ options: nil
1062
+ req = {
1063
+ session: session,
1064
+ sql: sql,
1065
+ transaction: transaction,
1066
+ params: params,
1067
+ param_types: param_types,
1068
+ partition_options: partition_options
1069
+ }.delete_if { |_, v| v.nil? }
1070
+ req = Google::Gax::to_proto(req, Google::Spanner::V1::PartitionQueryRequest)
1071
+ @partition_query.call(req, options)
1072
+ end
1073
+
1074
+ # Creates a set of partition tokens that can be used to execute a read
1075
+ # operation in parallel. Each of the returned partition tokens can be used
1076
+ # by {Google::Spanner::V1::Spanner::StreamingRead StreamingRead} to specify a subset of the read
1077
+ # result to read. The same session and read-only transaction must be used by
1078
+ # the PartitionReadRequest used to create the partition tokens and the
1079
+ # ReadRequests that use the partition tokens.
1080
+ # Partition tokens become invalid when the session used to create them
1081
+ # is deleted or begins a new transaction.
1082
+ #
1083
+ # @param session [String]
1084
+ # Required. The session used to create the partitions.
1085
+ # @param table [String]
1086
+ # Required. The name of the table in the database to be read.
1087
+ # @param key_set [Google::Spanner::V1::KeySet | Hash]
1088
+ # Required. +key_set+ identifies the rows to be yielded. +key_set+ names the
1089
+ # primary keys of the rows in {Google::Spanner::V1::PartitionReadRequest#table table} to be yielded, unless {Google::Spanner::V1::PartitionReadRequest#index index}
1090
+ # is present. If {Google::Spanner::V1::PartitionReadRequest#index index} is present, then {Google::Spanner::V1::PartitionReadRequest#key_set key_set} instead names
1091
+ # index keys in {Google::Spanner::V1::PartitionReadRequest#index index}.
1092
+ #
1093
+ # It is not an error for the +key_set+ to name rows that do not
1094
+ # exist in the database. Read yields nothing for nonexistent rows.
1095
+ # A hash of the same form as `Google::Spanner::V1::KeySet`
1096
+ # can also be provided.
1097
+ # @param transaction [Google::Spanner::V1::TransactionSelector | Hash]
1098
+ # Read only snapshot transactions are supported, read/write and single use
1099
+ # transactions are not.
1100
+ # A hash of the same form as `Google::Spanner::V1::TransactionSelector`
1101
+ # can also be provided.
1102
+ # @param index [String]
1103
+ # If non-empty, the name of an index on {Google::Spanner::V1::PartitionReadRequest#table table}. This index is
1104
+ # used instead of the table primary key when interpreting {Google::Spanner::V1::PartitionReadRequest#key_set key_set}
1105
+ # and sorting result rows. See {Google::Spanner::V1::PartitionReadRequest#key_set key_set} for further information.
1106
+ # @param columns [Array<String>]
1107
+ # The columns of {Google::Spanner::V1::PartitionReadRequest#table table} to be returned for each row matching
1108
+ # this request.
1109
+ # @param partition_options [Google::Spanner::V1::PartitionOptions | Hash]
1110
+ # Additional options that affect how many partitions are created.
1111
+ # A hash of the same form as `Google::Spanner::V1::PartitionOptions`
1112
+ # can also be provided.
1113
+ # @param options [Google::Gax::CallOptions]
1114
+ # Overrides the default settings for this call, e.g, timeout,
1115
+ # retries, etc.
1116
+ # @return [Google::Spanner::V1::PartitionResponse]
1117
+ # @raise [Google::Gax::GaxError] if the RPC is aborted.
1118
+ # @example
1119
+ # require "google/cloud/spanner/v1"
1120
+ #
1121
+ # spanner_client = Google::Cloud::Spanner::V1.new
1122
+ # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]")
1123
+ #
1124
+ # # TODO: Initialize +table+:
1125
+ # table = ''
1126
+ #
1127
+ # # TODO: Initialize +key_set+:
1128
+ # key_set = {}
1129
+ # response = spanner_client.partition_read(formatted_session, table, key_set)
1130
+
1131
+ def partition_read \
1132
+ session,
1133
+ table,
1134
+ key_set,
1135
+ transaction: nil,
1136
+ index: nil,
1137
+ columns: nil,
1138
+ partition_options: nil,
1139
+ options: nil
1140
+ req = {
1141
+ session: session,
1142
+ table: table,
1143
+ key_set: key_set,
1144
+ transaction: transaction,
1145
+ index: index,
1146
+ columns: columns,
1147
+ partition_options: partition_options
1148
+ }.delete_if { |_, v| v.nil? }
1149
+ req = Google::Gax::to_proto(req, Google::Spanner::V1::PartitionReadRequest)
1150
+ @partition_read.call(req, options)
1151
+ end
928
1152
  end
929
1153
  end
930
1154
  end