google-cloud-spanner-v1 0.18.0 → 0.20.0

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 (9) hide show
  1. checksums.yaml +4 -4
  2. data/AUTHENTICATION.md +72 -101
  3. data/lib/google/cloud/spanner/v1/spanner/client.rb +194 -123
  4. data/lib/google/cloud/spanner/v1/version.rb +1 -1
  5. data/lib/google/spanner/v1/spanner_pb.rb +7 -2
  6. data/lib/google/spanner/v1/spanner_services_pb.rb +37 -29
  7. data/proto_docs/google/api/client.rb +14 -0
  8. data/proto_docs/google/spanner/v1/spanner.rb +206 -78
  9. metadata +5 -5
data/lib/google/cloud/spanner/v1/spanner/client.rb CHANGED
@@ -33,6 +33,9 @@ module Google
33
33
  # transactions on data stored in Cloud Spanner databases.
34
34
  #
35
35
  class Client
36
+ # @private
37
+ DEFAULT_ENDPOINT_TEMPLATE = "spanner.$UNIVERSE_DOMAIN$"
38
+
36
39
  include Paths
37
40
 
38
41
  # @private
@@ -164,6 +167,15 @@ module Google
164
167
  @config
165
168
  end
166
169
 
170
+ ##
171
+ # The effective universe domain
172
+ #
173
+ # @return [String]
174
+ #
175
+ def universe_domain
176
+ @spanner_stub.universe_domain
177
+ end
178
+
167
179
  ##
168
180
  # Create a new Spanner client object.
169
181
  #
@@ -197,8 +209,9 @@ module Google
197
209
  credentials = @config.credentials
198
210
  # Use self-signed JWT if the endpoint is unchanged from default,
199
211
  # but only if the default endpoint does not have a region prefix.
200
- enable_self_signed_jwt = @config.endpoint == Configuration::DEFAULT_ENDPOINT &&
201
- !@config.endpoint.split(".").first.include?("-")
212
+ enable_self_signed_jwt = @config.endpoint.nil? ||
213
+ (@config.endpoint == Configuration::DEFAULT_ENDPOINT &&
214
+ !@config.endpoint.split(".").first.include?("-"))
202
215
  credentials ||= Credentials.default scope: @config.scope,
203
216
  enable_self_signed_jwt: enable_self_signed_jwt
204
217
  if credentials.is_a?(::String) || credentials.is_a?(::Hash)
@@ -209,8 +222,10 @@ module Google
209
222
 
210
223
  @spanner_stub = ::Gapic::ServiceStub.new(
211
224
  ::Google::Cloud::Spanner::V1::Spanner::Stub,
212
- credentials: credentials,
213
- endpoint: @config.endpoint,
225
+ credentials: credentials,
226
+ endpoint: @config.endpoint,
227
+ endpoint_template: DEFAULT_ENDPOINT_TEMPLATE,
228
+ universe_domain: @config.universe_domain,
214
229
  channel_args: @config.channel_args,
215
230
  interceptors: @config.interceptors,
216
231
  channel_pool_config: @config.channel_pool
@@ -354,7 +369,8 @@ module Google
354
369
  # The API may return fewer than the requested number of sessions. If a
355
370
  # specific number of sessions are desired, the client can make additional
356
371
  # calls to BatchCreateSessions (adjusting
357
- # {::Google::Cloud::Spanner::V1::BatchCreateSessionsRequest#session_count session_count} as necessary).
372
+ # {::Google::Cloud::Spanner::V1::BatchCreateSessionsRequest#session_count session_count}
373
+ # as necessary).
358
374
  #
359
375
  # @yield [response, operation] Access the result along with the RPC operation
360
376
  # @yieldparam response [::Google::Cloud::Spanner::V1::BatchCreateSessionsResponse]
@@ -532,7 +548,8 @@ module Google
532
548
  # to the server's maximum allowed page size.
533
549
  # @param page_token [::String]
534
550
  # If non-empty, `page_token` should contain a
535
- # {::Google::Cloud::Spanner::V1::ListSessionsResponse#next_page_token next_page_token} from a previous
551
+ # {::Google::Cloud::Spanner::V1::ListSessionsResponse#next_page_token next_page_token}
552
+ # from a previous
536
553
  # {::Google::Cloud::Spanner::V1::ListSessionsResponse ListSessionsResponse}.
537
554
  # @param filter [::String]
538
555
  # An expression for filtering the results of the request. Filter rules are
@@ -710,10 +727,12 @@ module Google
710
727
  #
711
728
  # Operations inside read-write transactions might return `ABORTED`. If
712
729
  # this occurs, the application should restart the transaction from
713
- # the beginning. See {::Google::Cloud::Spanner::V1::Transaction Transaction} for more details.
730
+ # the beginning. See {::Google::Cloud::Spanner::V1::Transaction Transaction} for more
731
+ # details.
714
732
  #
715
733
  # Larger result sets can be fetched in streaming fashion by calling
716
- # {::Google::Cloud::Spanner::V1::Spanner::Client#execute_streaming_sql ExecuteStreamingSql} instead.
734
+ # {::Google::Cloud::Spanner::V1::Spanner::Client#execute_streaming_sql ExecuteStreamingSql}
735
+ # instead.
717
736
  #
718
737
  # @overload execute_sql(request, options = nil)
719
738
  # Pass arguments to `execute_sql` via a request object, either of type
@@ -725,7 +744,7 @@ module Google
725
744
  # @param options [::Gapic::CallOptions, ::Hash]
726
745
  # Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
727
746
  #
728
- # @overload execute_sql(session: nil, transaction: nil, sql: nil, params: nil, param_types: nil, resume_token: nil, query_mode: nil, partition_token: nil, seqno: nil, query_options: nil, request_options: nil, data_boost_enabled: nil)
747
+ # @overload execute_sql(session: nil, transaction: nil, sql: nil, params: nil, param_types: nil, resume_token: nil, query_mode: nil, partition_token: nil, seqno: nil, query_options: nil, request_options: nil, directed_read_options: nil, data_boost_enabled: nil)
729
748
  # Pass arguments to `execute_sql` via keyword arguments. Note that at
730
749
  # least one keyword argument is required. To specify no parameters, or to keep all
731
750
  # the default parameter values, pass an empty Hash as a request object (see above).
@@ -762,7 +781,8 @@ module Google
762
781
  # @param param_types [::Hash{::String => ::Google::Cloud::Spanner::V1::Type, ::Hash}]
763
782
  # It is not always possible for Cloud Spanner to infer the right SQL type
764
783
  # from a JSON value. For example, values of type `BYTES` and values
765
- # of type `STRING` both appear in {::Google::Cloud::Spanner::V1::ExecuteSqlRequest#params params} as JSON strings.
784
+ # of type `STRING` both appear in
785
+ # {::Google::Cloud::Spanner::V1::ExecuteSqlRequest#params params} as JSON strings.
766
786
  #
767
787
  # In these cases, `param_types` can be used to specify the exact
768
788
  # SQL type for some or all of the SQL statement parameters. See the
@@ -771,14 +791,17 @@ module Google
771
791
  # @param resume_token [::String]
772
792
  # If this request is resuming a previously interrupted SQL statement
773
793
  # execution, `resume_token` should be copied from the last
774
- # {::Google::Cloud::Spanner::V1::PartialResultSet PartialResultSet} yielded before the interruption. Doing this
775
- # enables the new SQL statement execution to resume where the last one left
776
- # off. The rest of the request parameters must exactly match the
777
- # request that yielded this token.
794
+ # {::Google::Cloud::Spanner::V1::PartialResultSet PartialResultSet} yielded before the
795
+ # interruption. Doing this enables the new SQL statement execution to resume
796
+ # where the last one left off. The rest of the request parameters must
797
+ # exactly match the request that yielded this token.
778
798
  # @param query_mode [::Google::Cloud::Spanner::V1::ExecuteSqlRequest::QueryMode]
779
799
  # Used to control the amount of debugging information returned in
780
- # {::Google::Cloud::Spanner::V1::ResultSetStats ResultSetStats}. If {::Google::Cloud::Spanner::V1::ExecuteSqlRequest#partition_token partition_token} is set, {::Google::Cloud::Spanner::V1::ExecuteSqlRequest#query_mode query_mode} can only
781
- # be set to {::Google::Cloud::Spanner::V1::ExecuteSqlRequest::QueryMode::NORMAL QueryMode.NORMAL}.
800
+ # {::Google::Cloud::Spanner::V1::ResultSetStats ResultSetStats}. If
801
+ # {::Google::Cloud::Spanner::V1::ExecuteSqlRequest#partition_token partition_token} is
802
+ # set, {::Google::Cloud::Spanner::V1::ExecuteSqlRequest#query_mode query_mode} can only
803
+ # be set to
804
+ # {::Google::Cloud::Spanner::V1::ExecuteSqlRequest::QueryMode::NORMAL QueryMode.NORMAL}.
782
805
  # @param partition_token [::String]
783
806
  # If present, results will be restricted to the specified partition
784
807
  # previously created using PartitionQuery(). There must be an exact
@@ -799,12 +822,14 @@ module Google
799
822
  # Query optimizer configuration to use for the given query.
800
823
  # @param request_options [::Google::Cloud::Spanner::V1::RequestOptions, ::Hash]
801
824
  # Common options for this request.
825
+ # @param directed_read_options [::Google::Cloud::Spanner::V1::DirectedReadOptions, ::Hash]
826
+ # Directed read options for this request.
802
827
  # @param data_boost_enabled [::Boolean]
803
828
  # If this is for a partitioned query and this field is set to `true`, the
804
- # request will be executed via Spanner independent compute resources.
829
+ # request is executed with Spanner Data Boost independent compute resources.
805
830
  #
806
831
  # If the field is set to `true` but the request does not set
807
- # `partition_token`, the API will return an `INVALID_ARGUMENT` error.
832
+ # `partition_token`, the API returns an `INVALID_ARGUMENT` error.
808
833
  #
809
834
  # @yield [response, operation] Access the result along with the RPC operation
810
835
  # @yieldparam response [::Google::Cloud::Spanner::V1::ResultSet]
@@ -871,11 +896,11 @@ module Google
871
896
  end
872
897
 
873
898
  ##
874
- # Like {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql}, except returns the result
875
- # set as a stream. Unlike {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql}, there
876
- # is no limit on the size of the returned result set. However, no
877
- # individual row in the result set can exceed 100 MiB, and no
878
- # column value can exceed 10 MiB.
899
+ # Like {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql}, except returns the
900
+ # result set as a stream. Unlike
901
+ # {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql}, there is no limit on
902
+ # the size of the returned result set. However, no individual row in the
903
+ # result set can exceed 100 MiB, and no column value can exceed 10 MiB.
879
904
  #
880
905
  # @overload execute_streaming_sql(request, options = nil)
881
906
  # Pass arguments to `execute_streaming_sql` via a request object, either of type
@@ -887,7 +912,7 @@ module Google
887
912
  # @param options [::Gapic::CallOptions, ::Hash]
888
913
  # Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
889
914
  #
890
- # @overload execute_streaming_sql(session: nil, transaction: nil, sql: nil, params: nil, param_types: nil, resume_token: nil, query_mode: nil, partition_token: nil, seqno: nil, query_options: nil, request_options: nil, data_boost_enabled: nil)
915
+ # @overload execute_streaming_sql(session: nil, transaction: nil, sql: nil, params: nil, param_types: nil, resume_token: nil, query_mode: nil, partition_token: nil, seqno: nil, query_options: nil, request_options: nil, directed_read_options: nil, data_boost_enabled: nil)
891
916
  # Pass arguments to `execute_streaming_sql` via keyword arguments. Note that at
892
917
  # least one keyword argument is required. To specify no parameters, or to keep all
893
918
  # the default parameter values, pass an empty Hash as a request object (see above).
@@ -924,7 +949,8 @@ module Google
924
949
  # @param param_types [::Hash{::String => ::Google::Cloud::Spanner::V1::Type, ::Hash}]
925
950
  # It is not always possible for Cloud Spanner to infer the right SQL type
926
951
  # from a JSON value. For example, values of type `BYTES` and values
927
- # of type `STRING` both appear in {::Google::Cloud::Spanner::V1::ExecuteSqlRequest#params params} as JSON strings.
952
+ # of type `STRING` both appear in
953
+ # {::Google::Cloud::Spanner::V1::ExecuteSqlRequest#params params} as JSON strings.
928
954
  #
929
955
  # In these cases, `param_types` can be used to specify the exact
930
956
  # SQL type for some or all of the SQL statement parameters. See the
@@ -933,14 +959,17 @@ module Google
933
959
  # @param resume_token [::String]
934
960
  # If this request is resuming a previously interrupted SQL statement
935
961
  # execution, `resume_token` should be copied from the last
936
- # {::Google::Cloud::Spanner::V1::PartialResultSet PartialResultSet} yielded before the interruption. Doing this
937
- # enables the new SQL statement execution to resume where the last one left
938
- # off. The rest of the request parameters must exactly match the
939
- # request that yielded this token.
962
+ # {::Google::Cloud::Spanner::V1::PartialResultSet PartialResultSet} yielded before the
963
+ # interruption. Doing this enables the new SQL statement execution to resume
964
+ # where the last one left off. The rest of the request parameters must
965
+ # exactly match the request that yielded this token.
940
966
  # @param query_mode [::Google::Cloud::Spanner::V1::ExecuteSqlRequest::QueryMode]
941
967
  # Used to control the amount of debugging information returned in
942
- # {::Google::Cloud::Spanner::V1::ResultSetStats ResultSetStats}. If {::Google::Cloud::Spanner::V1::ExecuteSqlRequest#partition_token partition_token} is set, {::Google::Cloud::Spanner::V1::ExecuteSqlRequest#query_mode query_mode} can only
943
- # be set to {::Google::Cloud::Spanner::V1::ExecuteSqlRequest::QueryMode::NORMAL QueryMode.NORMAL}.
968
+ # {::Google::Cloud::Spanner::V1::ResultSetStats ResultSetStats}. If
969
+ # {::Google::Cloud::Spanner::V1::ExecuteSqlRequest#partition_token partition_token} is
970
+ # set, {::Google::Cloud::Spanner::V1::ExecuteSqlRequest#query_mode query_mode} can only
971
+ # be set to
972
+ # {::Google::Cloud::Spanner::V1::ExecuteSqlRequest::QueryMode::NORMAL QueryMode.NORMAL}.
944
973
  # @param partition_token [::String]
945
974
  # If present, results will be restricted to the specified partition
946
975
  # previously created using PartitionQuery(). There must be an exact
@@ -961,12 +990,14 @@ module Google
961
990
  # Query optimizer configuration to use for the given query.
962
991
  # @param request_options [::Google::Cloud::Spanner::V1::RequestOptions, ::Hash]
963
992
  # Common options for this request.
993
+ # @param directed_read_options [::Google::Cloud::Spanner::V1::DirectedReadOptions, ::Hash]
994
+ # Directed read options for this request.
964
995
  # @param data_boost_enabled [::Boolean]
965
996
  # If this is for a partitioned query and this field is set to `true`, the
966
- # request will be executed via Spanner independent compute resources.
997
+ # request is executed with Spanner Data Boost independent compute resources.
967
998
  #
968
999
  # If the field is set to `true` but the request does not set
969
- # `partition_token`, the API will return an `INVALID_ARGUMENT` error.
1000
+ # `partition_token`, the API returns an `INVALID_ARGUMENT` error.
970
1001
  #
971
1002
  # @yield [response, operation] Access the result along with the RPC operation
972
1003
  # @yieldparam response [::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>]
@@ -1041,9 +1072,10 @@ module Google
1041
1072
  # {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql}.
1042
1073
  #
1043
1074
  # Statements are executed in sequential order. A request can succeed even if
1044
- # a statement fails. The {::Google::Cloud::Spanner::V1::ExecuteBatchDmlResponse#status ExecuteBatchDmlResponse.status} field in the
1045
- # response provides information about the statement that failed. Clients must
1046
- # inspect this field to determine whether an error occurred.
1075
+ # a statement fails. The
1076
+ # {::Google::Cloud::Spanner::V1::ExecuteBatchDmlResponse#status ExecuteBatchDmlResponse.status}
1077
+ # field in the response provides information about the statement that failed.
1078
+ # Clients must inspect this field to determine whether an error occurred.
1047
1079
  #
1048
1080
  # Execution stops after the first failed statement; the remaining statements
1049
1081
  # are not executed.
@@ -1072,16 +1104,16 @@ module Google
1072
1104
  # caller must either supply an existing transaction ID or begin a new
1073
1105
  # transaction.
1074
1106
  # @param statements [::Array<::Google::Cloud::Spanner::V1::ExecuteBatchDmlRequest::Statement, ::Hash>]
1075
- # Required. The list of statements to execute in this batch. Statements are executed
1076
- # serially, such that the effects of statement `i` are visible to statement
1077
- # `i+1`. Each statement must be a DML statement. Execution stops at the
1078
- # first failed statement; the remaining statements are not executed.
1107
+ # Required. The list of statements to execute in this batch. Statements are
1108
+ # executed serially, such that the effects of statement `i` are visible to
1109
+ # statement `i+1`. Each statement must be a DML statement. Execution stops at
1110
+ # the first failed statement; the remaining statements are not executed.
1079
1111
  #
1080
1112
  # Callers must provide at least one statement.
1081
1113
  # @param seqno [::Integer]
1082
- # Required. A per-transaction sequence number used to identify this request. This field
1083
- # makes each request idempotent such that if the request is received multiple
1084
- # times, at most one will succeed.
1114
+ # Required. A per-transaction sequence number used to identify this request.
1115
+ # This field makes each request idempotent such that if the request is
1116
+ # received multiple times, at most one will succeed.
1085
1117
  #
1086
1118
  # The sequence number must be monotonically increasing within the
1087
1119
  # transaction. If a request arrives for the first time with an out-of-order
@@ -1157,14 +1189,15 @@ module Google
1157
1189
  ##
1158
1190
  # Reads rows from the database using key lookups and scans, as a
1159
1191
  # simple key/value style alternative to
1160
- # {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql}. This method cannot be used to
1161
- # return a result set larger than 10 MiB; if the read matches more
1192
+ # {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql}. This method cannot be
1193
+ # used to return a result set larger than 10 MiB; if the read matches more
1162
1194
  # data than that, the read fails with a `FAILED_PRECONDITION`
1163
1195
  # error.
1164
1196
  #
1165
1197
  # Reads inside read-write transactions might return `ABORTED`. If
1166
1198
  # this occurs, the application should restart the transaction from
1167
- # the beginning. See {::Google::Cloud::Spanner::V1::Transaction Transaction} for more details.
1199
+ # the beginning. See {::Google::Cloud::Spanner::V1::Transaction Transaction} for more
1200
+ # details.
1168
1201
  #
1169
1202
  # Larger result sets can be yielded in streaming fashion by calling
1170
1203
  # {::Google::Cloud::Spanner::V1::Spanner::Client#streaming_read StreamingRead} instead.
@@ -1179,7 +1212,7 @@ module Google
1179
1212
  # @param options [::Gapic::CallOptions, ::Hash]
1180
1213
  # Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
1181
1214
  #
1182
- # @overload read(session: nil, transaction: nil, table: nil, index: nil, columns: nil, key_set: nil, limit: nil, resume_token: nil, partition_token: nil, request_options: nil, data_boost_enabled: nil)
1215
+ # @overload read(session: nil, transaction: nil, table: nil, index: nil, columns: nil, key_set: nil, limit: nil, resume_token: nil, partition_token: nil, request_options: nil, directed_read_options: nil, data_boost_enabled: nil)
1183
1216
  # Pass arguments to `read` via keyword arguments. Note that at
1184
1217
  # least one keyword argument is required. To specify no parameters, or to keep all
1185
1218
  # the default parameter values, pass an empty Hash as a request object (see above).
@@ -1192,22 +1225,29 @@ module Google
1192
1225
  # @param table [::String]
1193
1226
  # Required. The name of the table in the database to be read.
1194
1227
  # @param index [::String]
1195
- # If non-empty, the name of an index on {::Google::Cloud::Spanner::V1::ReadRequest#table table}. This index is
1196
- # used instead of the table primary key when interpreting {::Google::Cloud::Spanner::V1::ReadRequest#key_set key_set}
1197
- # and sorting result rows. See {::Google::Cloud::Spanner::V1::ReadRequest#key_set key_set} for further information.
1228
+ # If non-empty, the name of an index on
1229
+ # {::Google::Cloud::Spanner::V1::ReadRequest#table table}. This index is used instead of
1230
+ # the table primary key when interpreting
1231
+ # {::Google::Cloud::Spanner::V1::ReadRequest#key_set key_set} and sorting result rows.
1232
+ # See {::Google::Cloud::Spanner::V1::ReadRequest#key_set key_set} for further
1233
+ # information.
1198
1234
  # @param columns [::Array<::String>]
1199
- # Required. The columns of {::Google::Cloud::Spanner::V1::ReadRequest#table table} to be returned for each row matching
1200
- # this request.
1235
+ # Required. The columns of {::Google::Cloud::Spanner::V1::ReadRequest#table table} to be
1236
+ # returned for each row matching this request.
1201
1237
  # @param key_set [::Google::Cloud::Spanner::V1::KeySet, ::Hash]
1202
1238
  # Required. `key_set` identifies the rows to be yielded. `key_set` names the
1203
- # primary keys of the rows in {::Google::Cloud::Spanner::V1::ReadRequest#table table} to be yielded, unless {::Google::Cloud::Spanner::V1::ReadRequest#index index}
1204
- # is present. If {::Google::Cloud::Spanner::V1::ReadRequest#index index} is present, then {::Google::Cloud::Spanner::V1::ReadRequest#key_set key_set} instead names
1205
- # index keys in {::Google::Cloud::Spanner::V1::ReadRequest#index index}.
1206
- #
1207
- # If the {::Google::Cloud::Spanner::V1::ReadRequest#partition_token partition_token} field is empty, rows are yielded
1208
- # in table primary key order (if {::Google::Cloud::Spanner::V1::ReadRequest#index index} is empty) or index key order
1209
- # (if {::Google::Cloud::Spanner::V1::ReadRequest#index index} is non-empty). If the {::Google::Cloud::Spanner::V1::ReadRequest#partition_token partition_token} field is not
1210
- # empty, rows will be yielded in an unspecified order.
1239
+ # primary keys of the rows in {::Google::Cloud::Spanner::V1::ReadRequest#table table} to
1240
+ # be yielded, unless {::Google::Cloud::Spanner::V1::ReadRequest#index index} is present.
1241
+ # If {::Google::Cloud::Spanner::V1::ReadRequest#index index} is present, then
1242
+ # {::Google::Cloud::Spanner::V1::ReadRequest#key_set key_set} instead names index keys
1243
+ # in {::Google::Cloud::Spanner::V1::ReadRequest#index index}.
1244
+ #
1245
+ # If the {::Google::Cloud::Spanner::V1::ReadRequest#partition_token partition_token}
1246
+ # field is empty, rows are yielded in table primary key order (if
1247
+ # {::Google::Cloud::Spanner::V1::ReadRequest#index index} is empty) or index key order
1248
+ # (if {::Google::Cloud::Spanner::V1::ReadRequest#index index} is non-empty). If the
1249
+ # {::Google::Cloud::Spanner::V1::ReadRequest#partition_token partition_token} field is
1250
+ # not empty, rows will be yielded in an unspecified order.
1211
1251
  #
1212
1252
  # It is not an error for the `key_set` to name rows that do not
1213
1253
  # exist in the database. Read yields nothing for nonexistent rows.
@@ -1218,9 +1258,9 @@ module Google
1218
1258
  # @param resume_token [::String]
1219
1259
  # If this request is resuming a previously interrupted read,
1220
1260
  # `resume_token` should be copied from the last
1221
- # {::Google::Cloud::Spanner::V1::PartialResultSet PartialResultSet} yielded before the interruption. Doing this
1222
- # enables the new read to resume where the last read left off. The
1223
- # rest of the request parameters must exactly match the request
1261
+ # {::Google::Cloud::Spanner::V1::PartialResultSet PartialResultSet} yielded before the
1262
+ # interruption. Doing this enables the new read to resume where the last read
1263
+ # left off. The rest of the request parameters must exactly match the request
1224
1264
  # that yielded this token.
1225
1265
  # @param partition_token [::String]
1226
1266
  # If present, results will be restricted to the specified partition
@@ -1229,12 +1269,14 @@ module Google
1229
1269
  # PartitionReadRequest message used to create this partition_token.
1230
1270
  # @param request_options [::Google::Cloud::Spanner::V1::RequestOptions, ::Hash]
1231
1271
  # Common options for this request.
1272
+ # @param directed_read_options [::Google::Cloud::Spanner::V1::DirectedReadOptions, ::Hash]
1273
+ # Directed read options for this request.
1232
1274
  # @param data_boost_enabled [::Boolean]
1233
1275
  # If this is for a partitioned read and this field is set to `true`, the
1234
- # request will be executed via Spanner independent compute resources.
1276
+ # request is executed with Spanner Data Boost independent compute resources.
1235
1277
  #
1236
1278
  # If the field is set to `true` but the request does not set
1237
- # `partition_token`, the API will return an `INVALID_ARGUMENT` error.
1279
+ # `partition_token`, the API returns an `INVALID_ARGUMENT` error.
1238
1280
  #
1239
1281
  # @yield [response, operation] Access the result along with the RPC operation
1240
1282
  # @yieldparam response [::Google::Cloud::Spanner::V1::ResultSet]
@@ -1301,9 +1343,9 @@ module Google
1301
1343
  end
1302
1344
 
1303
1345
  ##
1304
- # Like {::Google::Cloud::Spanner::V1::Spanner::Client#read Read}, except returns the result set as a
1305
- # stream. Unlike {::Google::Cloud::Spanner::V1::Spanner::Client#read Read}, there is no limit on the
1306
- # size of the returned result set. However, no individual row in
1346
+ # Like {::Google::Cloud::Spanner::V1::Spanner::Client#read Read}, except returns the result set
1347
+ # as a stream. Unlike {::Google::Cloud::Spanner::V1::Spanner::Client#read Read}, there is no
1348
+ # limit on the size of the returned result set. However, no individual row in
1307
1349
  # the result set can exceed 100 MiB, and no column value can exceed
1308
1350
  # 10 MiB.
1309
1351
  #
@@ -1317,7 +1359,7 @@ module Google
1317
1359
  # @param options [::Gapic::CallOptions, ::Hash]
1318
1360
  # Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
1319
1361
  #
1320
- # @overload streaming_read(session: nil, transaction: nil, table: nil, index: nil, columns: nil, key_set: nil, limit: nil, resume_token: nil, partition_token: nil, request_options: nil, data_boost_enabled: nil)
1362
+ # @overload streaming_read(session: nil, transaction: nil, table: nil, index: nil, columns: nil, key_set: nil, limit: nil, resume_token: nil, partition_token: nil, request_options: nil, directed_read_options: nil, data_boost_enabled: nil)
1321
1363
  # Pass arguments to `streaming_read` via keyword arguments. Note that at
1322
1364
  # least one keyword argument is required. To specify no parameters, or to keep all
1323
1365
  # the default parameter values, pass an empty Hash as a request object (see above).
@@ -1330,22 +1372,29 @@ module Google
1330
1372
  # @param table [::String]
1331
1373
  # Required. The name of the table in the database to be read.
1332
1374
  # @param index [::String]
1333
- # If non-empty, the name of an index on {::Google::Cloud::Spanner::V1::ReadRequest#table table}. This index is
1334
- # used instead of the table primary key when interpreting {::Google::Cloud::Spanner::V1::ReadRequest#key_set key_set}
1335
- # and sorting result rows. See {::Google::Cloud::Spanner::V1::ReadRequest#key_set key_set} for further information.
1375
+ # If non-empty, the name of an index on
1376
+ # {::Google::Cloud::Spanner::V1::ReadRequest#table table}. This index is used instead of
1377
+ # the table primary key when interpreting
1378
+ # {::Google::Cloud::Spanner::V1::ReadRequest#key_set key_set} and sorting result rows.
1379
+ # See {::Google::Cloud::Spanner::V1::ReadRequest#key_set key_set} for further
1380
+ # information.
1336
1381
  # @param columns [::Array<::String>]
1337
- # Required. The columns of {::Google::Cloud::Spanner::V1::ReadRequest#table table} to be returned for each row matching
1338
- # this request.
1382
+ # Required. The columns of {::Google::Cloud::Spanner::V1::ReadRequest#table table} to be
1383
+ # returned for each row matching this request.
1339
1384
  # @param key_set [::Google::Cloud::Spanner::V1::KeySet, ::Hash]
1340
1385
  # Required. `key_set` identifies the rows to be yielded. `key_set` names the
1341
- # primary keys of the rows in {::Google::Cloud::Spanner::V1::ReadRequest#table table} to be yielded, unless {::Google::Cloud::Spanner::V1::ReadRequest#index index}
1342
- # is present. If {::Google::Cloud::Spanner::V1::ReadRequest#index index} is present, then {::Google::Cloud::Spanner::V1::ReadRequest#key_set key_set} instead names
1343
- # index keys in {::Google::Cloud::Spanner::V1::ReadRequest#index index}.
1344
- #
1345
- # If the {::Google::Cloud::Spanner::V1::ReadRequest#partition_token partition_token} field is empty, rows are yielded
1346
- # in table primary key order (if {::Google::Cloud::Spanner::V1::ReadRequest#index index} is empty) or index key order
1347
- # (if {::Google::Cloud::Spanner::V1::ReadRequest#index index} is non-empty). If the {::Google::Cloud::Spanner::V1::ReadRequest#partition_token partition_token} field is not
1348
- # empty, rows will be yielded in an unspecified order.
1386
+ # primary keys of the rows in {::Google::Cloud::Spanner::V1::ReadRequest#table table} to
1387
+ # be yielded, unless {::Google::Cloud::Spanner::V1::ReadRequest#index index} is present.
1388
+ # If {::Google::Cloud::Spanner::V1::ReadRequest#index index} is present, then
1389
+ # {::Google::Cloud::Spanner::V1::ReadRequest#key_set key_set} instead names index keys
1390
+ # in {::Google::Cloud::Spanner::V1::ReadRequest#index index}.
1391
+ #
1392
+ # If the {::Google::Cloud::Spanner::V1::ReadRequest#partition_token partition_token}
1393
+ # field is empty, rows are yielded in table primary key order (if
1394
+ # {::Google::Cloud::Spanner::V1::ReadRequest#index index} is empty) or index key order
1395
+ # (if {::Google::Cloud::Spanner::V1::ReadRequest#index index} is non-empty). If the
1396
+ # {::Google::Cloud::Spanner::V1::ReadRequest#partition_token partition_token} field is
1397
+ # not empty, rows will be yielded in an unspecified order.
1349
1398
  #
1350
1399
  # It is not an error for the `key_set` to name rows that do not
1351
1400
  # exist in the database. Read yields nothing for nonexistent rows.
@@ -1356,9 +1405,9 @@ module Google
1356
1405
  # @param resume_token [::String]
1357
1406
  # If this request is resuming a previously interrupted read,
1358
1407
  # `resume_token` should be copied from the last
1359
- # {::Google::Cloud::Spanner::V1::PartialResultSet PartialResultSet} yielded before the interruption. Doing this
1360
- # enables the new read to resume where the last read left off. The
1361
- # rest of the request parameters must exactly match the request
1408
+ # {::Google::Cloud::Spanner::V1::PartialResultSet PartialResultSet} yielded before the
1409
+ # interruption. Doing this enables the new read to resume where the last read
1410
+ # left off. The rest of the request parameters must exactly match the request
1362
1411
  # that yielded this token.
1363
1412
  # @param partition_token [::String]
1364
1413
  # If present, results will be restricted to the specified partition
@@ -1367,12 +1416,14 @@ module Google
1367
1416
  # PartitionReadRequest message used to create this partition_token.
1368
1417
  # @param request_options [::Google::Cloud::Spanner::V1::RequestOptions, ::Hash]
1369
1418
  # Common options for this request.
1419
+ # @param directed_read_options [::Google::Cloud::Spanner::V1::DirectedReadOptions, ::Hash]
1420
+ # Directed read options for this request.
1370
1421
  # @param data_boost_enabled [::Boolean]
1371
1422
  # If this is for a partitioned read and this field is set to `true`, the
1372
- # request will be executed via Spanner independent compute resources.
1423
+ # request is executed with Spanner Data Boost independent compute resources.
1373
1424
  #
1374
1425
  # If the field is set to `true` but the request does not set
1375
- # `partition_token`, the API will return an `INVALID_ARGUMENT` error.
1426
+ # `partition_token`, the API returns an `INVALID_ARGUMENT` error.
1376
1427
  #
1377
1428
  # @yield [response, operation] Access the result along with the RPC operation
1378
1429
  # @yieldparam response [::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>]
@@ -1443,7 +1494,8 @@ module Google
1443
1494
 
1444
1495
  ##
1445
1496
  # Begins a new transaction. This step can often be skipped:
1446
- # {::Google::Cloud::Spanner::V1::Spanner::Client#read Read}, {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql} and
1497
+ # {::Google::Cloud::Spanner::V1::Spanner::Client#read Read},
1498
+ # {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql} and
1447
1499
  # {::Google::Cloud::Spanner::V1::Spanner::Client#commit Commit} can begin a new transaction as a
1448
1500
  # side-effect.
1449
1501
  #
@@ -1588,8 +1640,8 @@ module Google
1588
1640
  # this list.
1589
1641
  # @param return_commit_stats [::Boolean]
1590
1642
  # If `true`, then statistics related to the transaction will be included in
1591
- # the {::Google::Cloud::Spanner::V1::CommitResponse#commit_stats CommitResponse}. Default value is
1592
- # `false`.
1643
+ # the {::Google::Cloud::Spanner::V1::CommitResponse#commit_stats CommitResponse}.
1644
+ # Default value is `false`.
1593
1645
  # @param request_options [::Google::Cloud::Spanner::V1::RequestOptions, ::Hash]
1594
1646
  # Common options for this request.
1595
1647
  #
@@ -1660,8 +1712,9 @@ module Google
1660
1712
  ##
1661
1713
  # Rolls back a transaction, releasing any locks it holds. It is a good
1662
1714
  # idea to call this for any transaction that includes one or more
1663
- # {::Google::Cloud::Spanner::V1::Spanner::Client#read Read} or {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql} requests and
1664
- # ultimately decides not to commit.
1715
+ # {::Google::Cloud::Spanner::V1::Spanner::Client#read Read} or
1716
+ # {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql} requests and ultimately
1717
+ # decides not to commit.
1665
1718
  #
1666
1719
  # `Rollback` returns `OK` if it successfully aborts the transaction, the
1667
1720
  # transaction was already aborted, or the transaction is not
@@ -1754,10 +1807,11 @@ module Google
1754
1807
  ##
1755
1808
  # Creates a set of partition tokens that can be used to execute a query
1756
1809
  # operation in parallel. Each of the returned partition tokens can be used
1757
- # by {::Google::Cloud::Spanner::V1::Spanner::Client#execute_streaming_sql ExecuteStreamingSql} to specify a subset
1758
- # of the query result to read. The same session and read-only transaction
1759
- # must be used by the PartitionQueryRequest used to create the
1760
- # partition tokens and the ExecuteSqlRequests that use the partition tokens.
1810
+ # by {::Google::Cloud::Spanner::V1::Spanner::Client#execute_streaming_sql ExecuteStreamingSql} to
1811
+ # specify a subset of the query result to read. The same session and
1812
+ # read-only transaction must be used by the PartitionQueryRequest used to
1813
+ # create the partition tokens and the ExecuteSqlRequests that use the
1814
+ # partition tokens.
1761
1815
  #
1762
1816
  # Partition tokens become invalid when the session used to create them
1763
1817
  # is deleted, is idle for too long, begins a new transaction, or becomes too
@@ -1785,15 +1839,16 @@ module Google
1785
1839
  # Read only snapshot transactions are supported, read/write and single use
1786
1840
  # transactions are not.
1787
1841
  # @param sql [::String]
1788
- # Required. The query request to generate partitions for. The request will fail if
1789
- # the query is not root partitionable. The query plan of a root
1790
- # partitionable query has a single distributed union operator. A distributed
1791
- # union operator conceptually divides one or more tables into multiple
1792
- # splits, remotely evaluates a subquery independently on each split, and
1793
- # then unions all results.
1794
- #
1795
- # This must not contain DML commands, such as INSERT, UPDATE, or
1796
- # DELETE. Use {::Google::Cloud::Spanner::V1::Spanner::Client#execute_streaming_sql ExecuteStreamingSql} with a
1842
+ # Required. The query request to generate partitions for. The request will
1843
+ # fail if the query is not root partitionable. For a query to be root
1844
+ # partitionable, it needs to satisfy a few conditions. For example, the first
1845
+ # operator in the query execution plan must be a distributed union operator.
1846
+ # For more information about other conditions, see [Read data in
1847
+ # parallel](https://cloud.google.com/spanner/docs/reads#read_data_in_parallel).
1848
+ #
1849
+ # The query request must not contain DML commands, such as INSERT, UPDATE, or
1850
+ # DELETE. Use
1851
+ # {::Google::Cloud::Spanner::V1::Spanner::Client#execute_streaming_sql ExecuteStreamingSql} with a
1797
1852
  # PartitionedDml transaction for large, partition-friendly DML operations.
1798
1853
  # @param params [::Google::Protobuf::Struct, ::Hash]
1799
1854
  # Parameter names and values that bind to placeholders in the SQL string.
@@ -1811,7 +1866,8 @@ module Google
1811
1866
  # @param param_types [::Hash{::String => ::Google::Cloud::Spanner::V1::Type, ::Hash}]
1812
1867
  # It is not always possible for Cloud Spanner to infer the right SQL type
1813
1868
  # from a JSON value. For example, values of type `BYTES` and values
1814
- # of type `STRING` both appear in {::Google::Cloud::Spanner::V1::PartitionQueryRequest#params params} as JSON strings.
1869
+ # of type `STRING` both appear in
1870
+ # {::Google::Cloud::Spanner::V1::PartitionQueryRequest#params params} as JSON strings.
1815
1871
  #
1816
1872
  # In these cases, `param_types` can be used to specify the exact
1817
1873
  # SQL type for some or all of the SQL query parameters. See the
@@ -1887,12 +1943,13 @@ module Google
1887
1943
  ##
1888
1944
  # Creates a set of partition tokens that can be used to execute a read
1889
1945
  # operation in parallel. Each of the returned partition tokens can be used
1890
- # by {::Google::Cloud::Spanner::V1::Spanner::Client#streaming_read StreamingRead} to specify a subset of the read
1891
- # result to read. The same session and read-only transaction must be used by
1892
- # the PartitionReadRequest used to create the partition tokens and the
1893
- # ReadRequests that use the partition tokens. There are no ordering
1894
- # guarantees on rows returned among the returned partition tokens, or even
1895
- # within each individual StreamingRead call issued with a partition_token.
1946
+ # by {::Google::Cloud::Spanner::V1::Spanner::Client#streaming_read StreamingRead} to specify a
1947
+ # subset of the read result to read. The same session and read-only
1948
+ # transaction must be used by the PartitionReadRequest used to create the
1949
+ # partition tokens and the ReadRequests that use the partition tokens. There
1950
+ # are no ordering guarantees on rows returned among the returned partition
1951
+ # tokens, or even within each individual StreamingRead call issued with a
1952
+ # partition_token.
1896
1953
  #
1897
1954
  # Partition tokens become invalid when the session used to create them
1898
1955
  # is deleted, is idle for too long, begins a new transaction, or becomes too
@@ -1922,16 +1979,22 @@ module Google
1922
1979
  # @param table [::String]
1923
1980
  # Required. The name of the table in the database to be read.
1924
1981
  # @param index [::String]
1925
- # If non-empty, the name of an index on {::Google::Cloud::Spanner::V1::PartitionReadRequest#table table}. This index is
1926
- # used instead of the table primary key when interpreting {::Google::Cloud::Spanner::V1::PartitionReadRequest#key_set key_set}
1927
- # and sorting result rows. See {::Google::Cloud::Spanner::V1::PartitionReadRequest#key_set key_set} for further information.
1982
+ # If non-empty, the name of an index on
1983
+ # {::Google::Cloud::Spanner::V1::PartitionReadRequest#table table}. This index is used
1984
+ # instead of the table primary key when interpreting
1985
+ # {::Google::Cloud::Spanner::V1::PartitionReadRequest#key_set key_set} and sorting
1986
+ # result rows. See {::Google::Cloud::Spanner::V1::PartitionReadRequest#key_set key_set}
1987
+ # for further information.
1928
1988
  # @param columns [::Array<::String>]
1929
- # The columns of {::Google::Cloud::Spanner::V1::PartitionReadRequest#table table} to be returned for each row matching
1930
- # this request.
1989
+ # The columns of {::Google::Cloud::Spanner::V1::PartitionReadRequest#table table} to be
1990
+ # returned for each row matching this request.
1931
1991
  # @param key_set [::Google::Cloud::Spanner::V1::KeySet, ::Hash]
1932
1992
  # Required. `key_set` identifies the rows to be yielded. `key_set` names the
1933
- # primary keys of the rows in {::Google::Cloud::Spanner::V1::PartitionReadRequest#table table} to be yielded, unless {::Google::Cloud::Spanner::V1::PartitionReadRequest#index index}
1934
- # is present. If {::Google::Cloud::Spanner::V1::PartitionReadRequest#index index} is present, then {::Google::Cloud::Spanner::V1::PartitionReadRequest#key_set key_set} instead names
1993
+ # primary keys of the rows in
1994
+ # {::Google::Cloud::Spanner::V1::PartitionReadRequest#table table} to be yielded, unless
1995
+ # {::Google::Cloud::Spanner::V1::PartitionReadRequest#index index} is present. If
1996
+ # {::Google::Cloud::Spanner::V1::PartitionReadRequest#index index} is present, then
1997
+ # {::Google::Cloud::Spanner::V1::PartitionReadRequest#key_set key_set} instead names
1935
1998
  # index keys in {::Google::Cloud::Spanner::V1::PartitionReadRequest#index index}.
1936
1999
  #
1937
2000
  # It is not an error for the `key_set` to name rows that do not
@@ -2139,9 +2202,9 @@ module Google
2139
2202
  # end
2140
2203
  #
2141
2204
  # @!attribute [rw] endpoint
2142
- # The hostname or hostname:port of the service endpoint.
2143
- # Defaults to `"spanner.googleapis.com"`.
2144
- # @return [::String]
2205
+ # A custom service endpoint, as a hostname or hostname:port. The default is
2206
+ # nil, indicating to use the default endpoint in the current universe domain.
2207
+ # @return [::String,nil]
2145
2208
  # @!attribute [rw] credentials
2146
2209
  # Credentials to send with calls. You may provide any of the following types:
2147
2210
  # * (`String`) The path to a service account key file in JSON format
@@ -2187,13 +2250,20 @@ module Google
2187
2250
  # @!attribute [rw] quota_project
2188
2251
  # A separate project against which to charge quota.
2189
2252
  # @return [::String]
2253
+ # @!attribute [rw] universe_domain
2254
+ # The universe domain within which to make requests. This determines the
2255
+ # default endpoint URL. The default value of nil uses the environment
2256
+ # universe (usually the default "googleapis.com" universe).
2257
+ # @return [::String,nil]
2190
2258
  #
2191
2259
  class Configuration
2192
2260
  extend ::Gapic::Config
2193
2261
 
2262
+ # @private
2263
+ # The endpoint specific to the default "googleapis.com" universe. Deprecated.
2194
2264
  DEFAULT_ENDPOINT = "spanner.googleapis.com"
2195
2265
 
2196
- config_attr :endpoint, DEFAULT_ENDPOINT, ::String
2266
+ config_attr :endpoint, nil, ::String, nil
2197
2267
  config_attr :credentials, nil do |value|
2198
2268
  allowed = [::String, ::Hash, ::Proc, ::Symbol, ::Google::Auth::Credentials, ::Signet::OAuth2::Client, nil]
2199
2269
  allowed += [::GRPC::Core::Channel, ::GRPC::Core::ChannelCredentials] if defined? ::GRPC
@@ -2208,6 +2278,7 @@ module Google
2208
2278
  config_attr :metadata, nil, ::Hash, nil
2209
2279
  config_attr :retry_policy, nil, ::Hash, ::Proc, nil
2210
2280
  config_attr :quota_project, nil, ::String, nil
2281
+ config_attr :universe_domain, nil, ::String, nil
2211
2282
 
2212
2283
  # @private
2213
2284
  def initialize parent_config = nil