google-cloud-spanner-v1 0.18.0 → 0.20.0

Sign up to get free protection for your applications and to get access to all the features.
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