lib/google/cloud/spanner/v1/spanner_client.rb in google-cloud-spanner-1.6.3 vs lib/google/cloud/spanner/v1/spanner_client.rb in google-cloud-spanner-1.6.4

- old
+ new

@@ -296,14 +296,14 @@ # # Cloud Spanner limits the number of sessions that can exist at any given # time; thus, it is a good idea to delete idle and/or unneeded sessions. # Aside from explicit deletes, Cloud Spanner can delete sessions for which no # operations are sent for more than an hour. If a session is deleted, - # requests to it return +NOT_FOUND+. + # requests to it return `NOT_FOUND`. # # Idle sessions can be kept alive by sending a trivial SQL query - # periodically, e.g., +"SELECT 1"+. + # periodically, e.g., `"SELECT 1"`. # # @param database [String] # Required. The database in which the new session is created. # @param session [Google::Spanner::V1::Session | Hash] # The session to create. @@ -335,11 +335,11 @@ }.delete_if { |_, v| v.nil? } req = Google::Gax::to_proto(req, Google::Spanner::V1::CreateSessionRequest) @create_session.call(req, options, &block) end - # Gets a session. Returns +NOT_FOUND+ if the session does not exist. + # Gets a session. Returns `NOT_FOUND` if the session does not exist. # This is mainly useful for determining whether a session is still # alive. # # @param name [String] # Required. The name of the session to retrieve. @@ -381,16 +381,16 @@ # resources in a page. # @param filter [String] # An expression for filtering the results of the request. Filter rules are # case insensitive. The fields eligible for filtering are: # - # * +labels.key+ where key is the name of a label + # * `labels.key` where key is the name of a label # # Some examples of using filters are: # - # * +labels.env:*+ --> The session has the label "env". - # * +labels.env:dev+ --> The session has the label "env" and the value of + # * `labels.env:*` --> The session has the label "env". + # * `labels.env:dev` --> The session has the label "env" and the value of # the label contains the string "dev". # @param options [Google::Gax::CallOptions] # Overrides the default settings for this call, e.g, timeout, # retries, etc. # @yield [result, operation] Access the result along with the RPC operation @@ -464,64 +464,75 @@ req = Google::Gax::to_proto(req, Google::Spanner::V1::DeleteSessionRequest) @delete_session.call(req, options, &block) nil end - # Executes an SQL query, returning all rows in a single reply. This + # Executes an SQL statement, returning all results in a single reply. This # method cannot be used to return a result set larger than 10 MiB; # if the query yields more data than that, the query fails with - # a +FAILED_PRECONDITION+ error. + # a `FAILED_PRECONDITION` error. # - # Queries inside read-write transactions might return +ABORTED+. If + # Operations inside read-write transactions might return `ABORTED`. If # this occurs, the application should restart the transaction from # the beginning. See {Google::Spanner::V1::Transaction Transaction} for more details. # # Larger result sets can be fetched in streaming fashion by calling # {Google::Spanner::V1::Spanner::ExecuteStreamingSql ExecuteStreamingSql} instead. # # @param session [String] # Required. The session in which the SQL query should be performed. # @param sql [String] - # Required. The SQL query string. + # Required. The SQL string. # @param transaction [Google::Spanner::V1::TransactionSelector | Hash] # The transaction to use. If none is provided, the default is a # temporary read-only transaction with strong concurrency. + # + # The transaction to use. + # + # For queries, if none is provided, the default is a temporary read-only + # transaction with strong concurrency. + # + # Standard DML statements require a ReadWrite transaction. Single-use + # transactions are not supported (to avoid replay). The caller must + # either supply an existing transaction ID or begin a new transaction. + # + # Partitioned DML requires an existing PartitionedDml transaction ID. # A hash of the same form as `Google::Spanner::V1::TransactionSelector` # can also be provided. # @param params [Google::Protobuf::Struct | Hash] - # The SQL query string can contain parameter placeholders. A parameter - # placeholder consists of +'@'+ followed by the parameter + # The SQL string can contain parameter placeholders. A parameter + # placeholder consists of `'@'` followed by the parameter # name. Parameter names consist of any combination of letters, # numbers, and underscores. # # Parameters can appear anywhere that a literal value is expected. The same # parameter name can be used more than once, for example: - # +"WHERE id > @msg_id AND id < @msg_id + 100"+ + # `"WHERE id > @msg_id AND id < @msg_id + 100"` # - # It is an error to execute an SQL query with unbound parameters. + # It is an error to execute an SQL statement with unbound parameters. # - # Parameter values are specified using +params+, which is a JSON + # Parameter values are specified using `params`, which is a JSON # object whose keys are parameter names, and whose values are the # corresponding parameter values. # A hash of the same form as `Google::Protobuf::Struct` # can also be provided. # @param param_types [Hash{String => Google::Spanner::V1::Type | Hash}] # It is not always possible for Cloud Spanner to infer the right SQL type - # from a JSON value. For example, values of type +BYTES+ and values - # of type +STRING+ both appear in {Google::Spanner::V1::ExecuteSqlRequest#params params} as JSON strings. + # from a JSON value. For example, values of type `BYTES` and values + # of type `STRING` both appear in {Google::Spanner::V1::ExecuteSqlRequest#params params} as JSON strings. # - # In these cases, +param_types+ can be used to specify the exact - # SQL type for some or all of the SQL query parameters. See the + # In these cases, `param_types` can be used to specify the exact + # SQL type for some or all of the SQL statement parameters. See the # definition of {Google::Spanner::V1::Type Type} for more information # about SQL types. # A hash of the same form as `Google::Spanner::V1::Type` # can also be provided. # @param resume_token [String] - # If this request is resuming a previously interrupted SQL query - # execution, +resume_token+ should be copied from the last + # If this request is resuming a previously interrupted SQL statement + # execution, `resume_token` should be copied from the last # {Google::Spanner::V1::PartialResultSet PartialResultSet} yielded before the interruption. Doing this - # enables the new SQL query execution to resume where the last one left + # enables the new SQL statement execution to resume where the last one left # off. The rest of the request parameters must exactly match the # request that yielded this token. # @param query_mode [Google::Spanner::V1::ExecuteSqlRequest::QueryMode] # Used to control the amount of debugging information returned in # {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 @@ -529,10 +540,21 @@ # @param partition_token [String] # If present, results will be restricted to the specified partition # previously created using PartitionQuery(). There must be an exact # match for the values of fields common to this message and the # PartitionQueryRequest message used to create this partition_token. + # @param seqno [Integer] + # A per-transaction sequence number used to identify this request. This + # makes each request idempotent such that if the request is received multiple + # times, at most one will succeed. + # + # The sequence number must be monotonically increasing within the + # transaction. If a request arrives for the first time with an out-of-order + # sequence number, the transaction may be aborted. Replays of previously + # handled requests will yield the same response as the first execution. + # + # Required for DML statements. Ignored for queries. # @param options [Google::Gax::CallOptions] # Overrides the default settings for this call, e.g, timeout, # retries, etc. # @yield [result, operation] Access the result along with the RPC operation # @yieldparam result [Google::Spanner::V1::ResultSet] @@ -543,11 +565,11 @@ # require "google/cloud/spanner/v1" # # spanner_client = Google::Cloud::Spanner::V1::SpannerClient.new # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]") # - # # TODO: Initialize +sql+: + # # TODO: Initialize `sql`: # sql = '' # response = spanner_client.execute_sql(formatted_session, sql) def execute_sql \ session, @@ -556,21 +578,23 @@ params: nil, param_types: nil, resume_token: nil, query_mode: nil, partition_token: nil, + seqno: nil, options: nil, &block req = { session: session, sql: sql, transaction: transaction, params: params, param_types: param_types, resume_token: resume_token, query_mode: query_mode, - partition_token: partition_token + partition_token: partition_token, + seqno: seqno }.delete_if { |_, v| v.nil? } req = Google::Gax::to_proto(req, Google::Spanner::V1::ExecuteSqlRequest) @execute_sql.call(req, options, &block) end @@ -581,49 +605,60 @@ # column value can exceed 10 MiB. # # @param session [String] # Required. The session in which the SQL query should be performed. # @param sql [String] - # Required. The SQL query string. + # Required. The SQL string. # @param transaction [Google::Spanner::V1::TransactionSelector | Hash] # The transaction to use. If none is provided, the default is a # temporary read-only transaction with strong concurrency. + # + # The transaction to use. + # + # For queries, if none is provided, the default is a temporary read-only + # transaction with strong concurrency. + # + # Standard DML statements require a ReadWrite transaction. Single-use + # transactions are not supported (to avoid replay). The caller must + # either supply an existing transaction ID or begin a new transaction. + # + # Partitioned DML requires an existing PartitionedDml transaction ID. # A hash of the same form as `Google::Spanner::V1::TransactionSelector` # can also be provided. # @param params [Google::Protobuf::Struct | Hash] - # The SQL query string can contain parameter placeholders. A parameter - # placeholder consists of +'@'+ followed by the parameter + # The SQL string can contain parameter placeholders. A parameter + # placeholder consists of `'@'` followed by the parameter # name. Parameter names consist of any combination of letters, # numbers, and underscores. # # Parameters can appear anywhere that a literal value is expected. The same # parameter name can be used more than once, for example: - # +"WHERE id > @msg_id AND id < @msg_id + 100"+ + # `"WHERE id > @msg_id AND id < @msg_id + 100"` # - # It is an error to execute an SQL query with unbound parameters. + # It is an error to execute an SQL statement with unbound parameters. # - # Parameter values are specified using +params+, which is a JSON + # Parameter values are specified using `params`, which is a JSON # object whose keys are parameter names, and whose values are the # corresponding parameter values. # A hash of the same form as `Google::Protobuf::Struct` # can also be provided. # @param param_types [Hash{String => Google::Spanner::V1::Type | Hash}] # It is not always possible for Cloud Spanner to infer the right SQL type - # from a JSON value. For example, values of type +BYTES+ and values - # of type +STRING+ both appear in {Google::Spanner::V1::ExecuteSqlRequest#params params} as JSON strings. + # from a JSON value. For example, values of type `BYTES` and values + # of type `STRING` both appear in {Google::Spanner::V1::ExecuteSqlRequest#params params} as JSON strings. # - # In these cases, +param_types+ can be used to specify the exact - # SQL type for some or all of the SQL query parameters. See the + # In these cases, `param_types` can be used to specify the exact + # SQL type for some or all of the SQL statement parameters. See the # definition of {Google::Spanner::V1::Type Type} for more information # about SQL types. # A hash of the same form as `Google::Spanner::V1::Type` # can also be provided. # @param resume_token [String] - # If this request is resuming a previously interrupted SQL query - # execution, +resume_token+ should be copied from the last + # If this request is resuming a previously interrupted SQL statement + # execution, `resume_token` should be copied from the last # {Google::Spanner::V1::PartialResultSet PartialResultSet} yielded before the interruption. Doing this - # enables the new SQL query execution to resume where the last one left + # enables the new SQL statement execution to resume where the last one left # off. The rest of the request parameters must exactly match the # request that yielded this token. # @param query_mode [Google::Spanner::V1::ExecuteSqlRequest::QueryMode] # Used to control the amount of debugging information returned in # {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 @@ -631,10 +666,21 @@ # @param partition_token [String] # If present, results will be restricted to the specified partition # previously created using PartitionQuery(). There must be an exact # match for the values of fields common to this message and the # PartitionQueryRequest message used to create this partition_token. + # @param seqno [Integer] + # A per-transaction sequence number used to identify this request. This + # makes each request idempotent such that if the request is received multiple + # times, at most one will succeed. + # + # The sequence number must be monotonically increasing within the + # transaction. If a request arrives for the first time with an out-of-order + # sequence number, the transaction may be aborted. Replays of previously + # handled requests will yield the same response as the first execution. + # + # Required for DML statements. Ignored for queries. # @param options [Google::Gax::CallOptions] # Overrides the default settings for this call, e.g, timeout, # retries, etc. # @return [Enumerable<Google::Spanner::V1::PartialResultSet>] # An enumerable of Google::Spanner::V1::PartialResultSet instances. @@ -644,11 +690,11 @@ # require "google/cloud/spanner/v1" # # spanner_client = Google::Cloud::Spanner::V1::SpannerClient.new # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]") # - # # TODO: Initialize +sql+: + # # TODO: Initialize `sql`: # sql = '' # spanner_client.execute_streaming_sql(formatted_session, sql).each do |element| # # Process element. # end @@ -659,33 +705,35 @@ params: nil, param_types: nil, resume_token: nil, query_mode: nil, partition_token: nil, + seqno: nil, options: nil req = { session: session, sql: sql, transaction: transaction, params: params, param_types: param_types, resume_token: resume_token, query_mode: query_mode, - partition_token: partition_token + partition_token: partition_token, + seqno: seqno }.delete_if { |_, v| v.nil? } req = Google::Gax::to_proto(req, Google::Spanner::V1::ExecuteSqlRequest) @execute_streaming_sql.call(req, options) end # Reads rows from the database using key lookups and scans, as a # simple key/value style alternative to # {Google::Spanner::V1::Spanner::ExecuteSql ExecuteSql}. This method cannot be used to # return a result set larger than 10 MiB; if the read matches more - # data than that, the read fails with a +FAILED_PRECONDITION+ + # data than that, the read fails with a `FAILED_PRECONDITION` # error. # - # Reads inside read-write transactions might return +ABORTED+. If + # Reads inside read-write transactions might return `ABORTED`. If # this occurs, the application should restart the transaction from # the beginning. See {Google::Spanner::V1::Transaction Transaction} for more details. # # Larger result sets can be yielded in streaming fashion by calling # {Google::Spanner::V1::Spanner::StreamingRead StreamingRead} instead. @@ -696,21 +744,21 @@ # Required. The name of the table in the database to be read. # @param columns [Array<String>] # The columns of {Google::Spanner::V1::ReadRequest#table table} to be returned for each row matching # this request. # @param key_set [Google::Spanner::V1::KeySet | Hash] - # Required. +key_set+ identifies the rows to be yielded. +key_set+ names the + # Required. `key_set` identifies the rows to be yielded. `key_set` names the # primary keys of the rows in {Google::Spanner::V1::ReadRequest#table table} to be yielded, unless {Google::Spanner::V1::ReadRequest#index index} # is present. If {Google::Spanner::V1::ReadRequest#index index} is present, then {Google::Spanner::V1::ReadRequest#key_set key_set} instead names # index keys in {Google::Spanner::V1::ReadRequest#index index}. # # If the {Google::Spanner::V1::ReadRequest#partition_token partition_token} field is empty, rows are yielded # in table primary key order (if {Google::Spanner::V1::ReadRequest#index index} is empty) or index key order # (if {Google::Spanner::V1::ReadRequest#index index} is non-empty). If the {Google::Spanner::V1::ReadRequest#partition_token partition_token} field is not # empty, rows will be yielded in an unspecified order. # - # It is not an error for the +key_set+ to name rows that do not + # It is not an error for the `key_set` to name rows that do not # exist in the database. Read yields nothing for nonexistent rows. # A hash of the same form as `Google::Spanner::V1::KeySet` # can also be provided. # @param transaction [Google::Spanner::V1::TransactionSelector | Hash] # The transaction to use. If none is provided, the default is a @@ -720,16 +768,16 @@ # @param index [String] # If non-empty, the name of an index on {Google::Spanner::V1::ReadRequest#table table}. This index is # used instead of the table primary key when interpreting {Google::Spanner::V1::ReadRequest#key_set key_set} # and sorting result rows. See {Google::Spanner::V1::ReadRequest#key_set key_set} for further information. # @param limit [Integer] - # If greater than zero, only the first +limit+ rows are yielded. If +limit+ + # If greater than zero, only the first `limit` rows are yielded. If `limit` # is zero, the default is no limit. A limit cannot be specified if - # +partition_token+ is set. + # `partition_token` is set. # @param resume_token [String] # If this request is resuming a previously interrupted read, - # +resume_token+ should be copied from the last + # `resume_token` should be copied from the last # {Google::Spanner::V1::PartialResultSet PartialResultSet} yielded before the interruption. Doing this # enables the new read to resume where the last read left off. The # rest of the request parameters must exactly match the request # that yielded this token. # @param partition_token [String] @@ -749,17 +797,17 @@ # require "google/cloud/spanner/v1" # # spanner_client = Google::Cloud::Spanner::V1::SpannerClient.new # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]") # - # # TODO: Initialize +table+: + # # TODO: Initialize `table`: # table = '' # - # # TODO: Initialize +columns+: + # # TODO: Initialize `columns`: # columns = [] # - # # TODO: Initialize +key_set+: + # # TODO: Initialize `key_set`: # key_set = {} # response = spanner_client.read(formatted_session, table, columns, key_set) def read \ session, @@ -800,21 +848,21 @@ # Required. The name of the table in the database to be read. # @param columns [Array<String>] # The columns of {Google::Spanner::V1::ReadRequest#table table} to be returned for each row matching # this request. # @param key_set [Google::Spanner::V1::KeySet | Hash] - # Required. +key_set+ identifies the rows to be yielded. +key_set+ names the + # Required. `key_set` identifies the rows to be yielded. `key_set` names the # primary keys of the rows in {Google::Spanner::V1::ReadRequest#table table} to be yielded, unless {Google::Spanner::V1::ReadRequest#index index} # is present. If {Google::Spanner::V1::ReadRequest#index index} is present, then {Google::Spanner::V1::ReadRequest#key_set key_set} instead names # index keys in {Google::Spanner::V1::ReadRequest#index index}. # # If the {Google::Spanner::V1::ReadRequest#partition_token partition_token} field is empty, rows are yielded # in table primary key order (if {Google::Spanner::V1::ReadRequest#index index} is empty) or index key order # (if {Google::Spanner::V1::ReadRequest#index index} is non-empty). If the {Google::Spanner::V1::ReadRequest#partition_token partition_token} field is not # empty, rows will be yielded in an unspecified order. # - # It is not an error for the +key_set+ to name rows that do not + # It is not an error for the `key_set` to name rows that do not # exist in the database. Read yields nothing for nonexistent rows. # A hash of the same form as `Google::Spanner::V1::KeySet` # can also be provided. # @param transaction [Google::Spanner::V1::TransactionSelector | Hash] # The transaction to use. If none is provided, the default is a @@ -824,16 +872,16 @@ # @param index [String] # If non-empty, the name of an index on {Google::Spanner::V1::ReadRequest#table table}. This index is # used instead of the table primary key when interpreting {Google::Spanner::V1::ReadRequest#key_set key_set} # and sorting result rows. See {Google::Spanner::V1::ReadRequest#key_set key_set} for further information. # @param limit [Integer] - # If greater than zero, only the first +limit+ rows are yielded. If +limit+ + # If greater than zero, only the first `limit` rows are yielded. If `limit` # is zero, the default is no limit. A limit cannot be specified if - # +partition_token+ is set. + # `partition_token` is set. # @param resume_token [String] # If this request is resuming a previously interrupted read, - # +resume_token+ should be copied from the last + # `resume_token` should be copied from the last # {Google::Spanner::V1::PartialResultSet PartialResultSet} yielded before the interruption. Doing this # enables the new read to resume where the last read left off. The # rest of the request parameters must exactly match the request # that yielded this token. # @param partition_token [String] @@ -852,17 +900,17 @@ # require "google/cloud/spanner/v1" # # spanner_client = Google::Cloud::Spanner::V1::SpannerClient.new # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]") # - # # TODO: Initialize +table+: + # # TODO: Initialize `table`: # table = '' # - # # TODO: Initialize +columns+: + # # TODO: Initialize `columns`: # columns = [] # - # # TODO: Initialize +key_set+: + # # TODO: Initialize `key_set`: # key_set = {} # spanner_client.streaming_read(formatted_session, table, columns, key_set).each do |element| # # Process element. # end @@ -915,11 +963,11 @@ # require "google/cloud/spanner/v1" # # spanner_client = Google::Cloud::Spanner::V1::SpannerClient.new # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]") # - # # TODO: Initialize +options_+: + # # TODO: Initialize `options_`: # options_ = {} # response = spanner_client.begin_transaction(formatted_session, options_) def begin_transaction \ session, @@ -935,14 +983,14 @@ end # Commits a transaction. The request includes the mutations to be # applied to rows in the database. # - # +Commit+ might return an +ABORTED+ error. This can occur at any time; + # `Commit` might return an `ABORTED` error. This can occur at any time; # commonly, the cause is conflicts with concurrent # transactions. However, it can also happen for a variety of other - # reasons. If +Commit+ returns +ABORTED+, the caller should re-attempt + # reasons. If `Commit` returns `ABORTED`, the caller should re-attempt # the transaction from the beginning, re-using the same session. # # @param session [String] # Required. The session in which the transaction to be committed is running. # @param mutations [Array<Google::Spanner::V1::Mutation | Hash>] @@ -955,11 +1003,11 @@ # Commit a previously-started transaction. # @param single_use_transaction [Google::Spanner::V1::TransactionOptions | Hash] # Execute mutations in a temporary transaction. Note that unlike # commit of a previously-started transaction, commit with a # temporary transaction is non-idempotent. That is, if the - # +CommitRequest+ is sent to Cloud Spanner more than once (for + # `CommitRequest` is sent to Cloud Spanner more than once (for # instance, due to retries in the application, or in the # transport library), it is possible that the mutations are # executed more than once. If this is undesirable, use # {Google::Spanner::V1::Spanner::BeginTransaction BeginTransaction} and # {Google::Spanner::V1::Spanner::Commit Commit} instead. @@ -977,11 +1025,11 @@ # require "google/cloud/spanner/v1" # # spanner_client = Google::Cloud::Spanner::V1::SpannerClient.new # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]") # - # # TODO: Initialize +mutations+: + # # TODO: Initialize `mutations`: # mutations = [] # response = spanner_client.commit(formatted_session, mutations) def commit \ session, @@ -1003,13 +1051,13 @@ # Rolls back a transaction, releasing any locks it holds. It is a good # idea to call this for any transaction that includes one or more # {Google::Spanner::V1::Spanner::Read Read} or {Google::Spanner::V1::Spanner::ExecuteSql ExecuteSql} requests and # ultimately decides not to commit. # - # +Rollback+ returns +OK+ if it successfully aborts the transaction, the + # `Rollback` returns `OK` if it successfully aborts the transaction, the # transaction was already aborted, or the transaction is not - # found. +Rollback+ never returns +ABORTED+. + # found. `Rollback` never returns `ABORTED`. # # @param session [String] # Required. The session in which the transaction to roll back is running. # @param transaction_id [String] # Required. The transaction to roll back. @@ -1024,11 +1072,11 @@ # require "google/cloud/spanner/v1" # # spanner_client = Google::Cloud::Spanner::V1::SpannerClient.new # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]") # - # # TODO: Initialize +transaction_id+: + # # TODO: Initialize `transaction_id`: # transaction_id = '' # spanner_client.rollback(formatted_session, transaction_id) def rollback \ session, @@ -1048,50 +1096,57 @@ # operation in parallel. Each of the returned partition tokens can be used # by {Google::Spanner::V1::Spanner::ExecuteStreamingSql ExecuteStreamingSql} to specify a subset # of the query result to read. The same session and read-only transaction # must be used by the PartitionQueryRequest used to create the # partition tokens and the ExecuteSqlRequests that use the partition tokens. + # # Partition tokens become invalid when the session used to create them - # is deleted or begins a new transaction. + # is deleted, is idle for too long, begins a new transaction, or becomes too + # old. When any of these happen, it is not possible to resume the query, and + # the whole operation must be restarted from the beginning. # # @param session [String] # Required. The session used to create the partitions. # @param sql [String] # The query request to generate partitions for. The request will fail if # the query is not root partitionable. The query plan of a root # partitionable query has a single distributed union operator. A distributed # union operator conceptually divides one or more tables into multiple # splits, remotely evaluates a subquery independently on each split, and # then unions all results. + # + # This must not contain DML commands, such as INSERT, UPDATE, or + # DELETE. Use {Google::Spanner::V1::Spanner::ExecuteStreamingSql ExecuteStreamingSql} with a + # PartitionedDml transaction for large, partition-friendly DML operations. # @param transaction [Google::Spanner::V1::TransactionSelector | Hash] # Read only snapshot transactions are supported, read/write and single use # transactions are not. # A hash of the same form as `Google::Spanner::V1::TransactionSelector` # can also be provided. # @param params [Google::Protobuf::Struct | Hash] # The SQL query string can contain parameter placeholders. A parameter - # placeholder consists of +'@'+ followed by the parameter + # placeholder consists of `'@'` followed by the parameter # name. Parameter names consist of any combination of letters, # numbers, and underscores. # # Parameters can appear anywhere that a literal value is expected. The same # parameter name can be used more than once, for example: - # +"WHERE id > @msg_id AND id < @msg_id + 100"+ + # `"WHERE id > @msg_id AND id < @msg_id + 100"` # # It is an error to execute an SQL query with unbound parameters. # - # Parameter values are specified using +params+, which is a JSON + # Parameter values are specified using `params`, which is a JSON # object whose keys are parameter names, and whose values are the # corresponding parameter values. # A hash of the same form as `Google::Protobuf::Struct` # can also be provided. # @param param_types [Hash{String => Google::Spanner::V1::Type | Hash}] # It is not always possible for Cloud Spanner to infer the right SQL type - # from a JSON value. For example, values of type +BYTES+ and values - # of type +STRING+ both appear in {Google::Spanner::V1::PartitionQueryRequest#params params} as JSON strings. + # from a JSON value. For example, values of type `BYTES` and values + # of type `STRING` both appear in {Google::Spanner::V1::PartitionQueryRequest#params params} as JSON strings. # - # In these cases, +param_types+ can be used to specify the exact + # In these cases, `param_types` can be used to specify the exact # SQL type for some or all of the SQL query parameters. See the # definition of {Google::Spanner::V1::Type Type} for more information # about SQL types. # A hash of the same form as `Google::Spanner::V1::Type` # can also be provided. @@ -1111,11 +1166,11 @@ # require "google/cloud/spanner/v1" # # spanner_client = Google::Cloud::Spanner::V1::SpannerClient.new # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]") # - # # TODO: Initialize +sql+: + # # TODO: Initialize `sql`: # sql = '' # response = spanner_client.partition_query(formatted_session, sql) def partition_query \ session, @@ -1141,25 +1196,30 @@ # Creates a set of partition tokens that can be used to execute a read # operation in parallel. Each of the returned partition tokens can be used # by {Google::Spanner::V1::Spanner::StreamingRead StreamingRead} to specify a subset of the read # result to read. The same session and read-only transaction must be used by # the PartitionReadRequest used to create the partition tokens and the - # ReadRequests that use the partition tokens. + # ReadRequests that use the partition tokens. There are no ordering + # guarantees on rows returned among the returned partition tokens, or even + # within each individual StreamingRead call issued with a partition_token. + # # Partition tokens become invalid when the session used to create them - # is deleted or begins a new transaction. + # is deleted, is idle for too long, begins a new transaction, or becomes too + # old. When any of these happen, it is not possible to resume the read, and + # the whole operation must be restarted from the beginning. # # @param session [String] # Required. The session used to create the partitions. # @param table [String] # Required. The name of the table in the database to be read. # @param key_set [Google::Spanner::V1::KeySet | Hash] - # Required. +key_set+ identifies the rows to be yielded. +key_set+ names the + # Required. `key_set` identifies the rows to be yielded. `key_set` names the # primary keys of the rows in {Google::Spanner::V1::PartitionReadRequest#table table} to be yielded, unless {Google::Spanner::V1::PartitionReadRequest#index index} # is present. If {Google::Spanner::V1::PartitionReadRequest#index index} is present, then {Google::Spanner::V1::PartitionReadRequest#key_set key_set} instead names # index keys in {Google::Spanner::V1::PartitionReadRequest#index index}. # - # It is not an error for the +key_set+ to name rows that do not + # It is not an error for the `key_set` to name rows that do not # exist in the database. Read yields nothing for nonexistent rows. # A hash of the same form as `Google::Spanner::V1::KeySet` # can also be provided. # @param transaction [Google::Spanner::V1::TransactionSelector | Hash] # Read only snapshot transactions are supported, read/write and single use @@ -1189,13 +1249,13 @@ # require "google/cloud/spanner/v1" # # spanner_client = Google::Cloud::Spanner::V1::SpannerClient.new # formatted_session = Google::Cloud::Spanner::V1::SpannerClient.session_path("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]") # - # # TODO: Initialize +table+: + # # TODO: Initialize `table`: # table = '' # - # # TODO: Initialize +key_set+: + # # TODO: Initialize `key_set`: # key_set = {} # response = spanner_client.partition_read(formatted_session, table, key_set) def partition_read \ session,