google-cloud-spanner 1.12.0 → 1.12.2

data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/keys.rb

@@ -137,8 +137,8 @@ module Google
       #     encoded as described {Google::Spanner::V1::TypeCode here}.
       # @!attribute [rw] ranges
       #   @return [Array<Google::Spanner::V1::KeyRange>]
-      #     A list of key ranges. See {Google::Spanner::V1::KeyRange KeyRange} for more
-      #     information about key range specifications.
+      #     A list of key ranges. See {Google::Spanner::V1::KeyRange KeyRange} for more information about
+      #     key range specifications.
       # @!attribute [rw] all
       #   @return [true, false]
       #     For convenience `all` can be set to `true` to indicate that this

data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/mutation.rb

@@ -29,32 +29,33 @@ module Google
       #     already exist, the transaction fails with error `NOT_FOUND`.
       # @!attribute [rw] insert_or_update
       #   @return [Google::Spanner::V1::Mutation::Write]
-      #     Like {Google::Spanner::V1::Mutation#insert insert}, except that if the row
-      #     already exists, then its column values are overwritten with the ones
-      #     provided. Any column values not explicitly written are preserved.
+      #     Like {Google::Spanner::V1::Mutation#insert insert}, except that if the row already exists, then
+      #     its column values are overwritten with the ones provided. Any
+      #     column values not explicitly written are preserved.
       # @!attribute [rw] replace
       #   @return [Google::Spanner::V1::Mutation::Write]
-      #     Like {Google::Spanner::V1::Mutation#insert insert}, except that if the row
-      #     already exists, it is deleted, and the column values provided are
-      #     inserted instead. Unlike
-      #     {Google::Spanner::V1::Mutation#insert_or_update insert_or_update}, this
-      #     means any values not explicitly written become `NULL`.
+      #     Like {Google::Spanner::V1::Mutation#insert insert}, except that if the row already exists, it is
+      #     deleted, and the column values provided are inserted
+      #     instead. Unlike {Google::Spanner::V1::Mutation#insert_or_update insert_or_update}, this means any values not
+      #     explicitly written become `NULL`.
+      #
+      #     In an interleaved table, if you create the child table with the
+      #     `ON DELETE CASCADE` annotation, then replacing a parent row
+      #     also deletes the child rows. Otherwise, you must delete the
+      #     child rows before you replace the parent row.
       # @!attribute [rw] delete
       #   @return [Google::Spanner::V1::Mutation::Delete]
       #     Delete rows from a table. Succeeds whether or not the named
       #     rows were present.
       class Mutation
-        # Arguments to {Google::Spanner::V1::Mutation#insert insert},
-        # {Google::Spanner::V1::Mutation#update update},
-        # {Google::Spanner::V1::Mutation#insert_or_update insert_or_update}, and
+        # Arguments to {Google::Spanner::V1::Mutation#insert insert}, {Google::Spanner::V1::Mutation#update update}, {Google::Spanner::V1::Mutation#insert_or_update insert_or_update}, and
         # {Google::Spanner::V1::Mutation#replace replace} operations.
         # @!attribute [rw] table
         #   @return [String]
         #     Required. The table whose rows will be written.
         # @!attribute [rw] columns
         #   @return [Array<String>]
-        #     The names of the columns in
-        #     {Google::Spanner::V1::Mutation::Write#table table} to be written.
+        #     The names of the columns in {Google::Spanner::V1::Mutation::Write#table table} to be written.
         #
         #     The list of columns must contain enough columns to allow
         #     Cloud Spanner to derive values for all primary key columns in the
@@ -64,13 +65,11 @@ module Google
         #     The values to be written. `values` can contain more than one
         #     list of values. If it does, then multiple rows are written, one
         #     for each entry in `values`. Each list in `values` must have
-        #     exactly as many entries as there are entries in
-        #     {Google::Spanner::V1::Mutation::Write#columns columns} above. Sending
-        #     multiple lists is equivalent to sending multiple `Mutation`s, each
-        #     containing one `values` entry and repeating
-        #     {Google::Spanner::V1::Mutation::Write#table table} and
-        #     {Google::Spanner::V1::Mutation::Write#columns columns}. Individual values in
-        #     each list are encoded as described {Google::Spanner::V1::TypeCode here}.
+        #     exactly as many entries as there are entries in {Google::Spanner::V1::Mutation::Write#columns columns}
+        #     above. Sending multiple lists is equivalent to sending multiple
+        #     `Mutation`s, each containing one `values` entry and repeating
+        #     {Google::Spanner::V1::Mutation::Write#table table} and {Google::Spanner::V1::Mutation::Write#columns columns}. Individual values in each list are
+        #     encoded as described {Google::Spanner::V1::TypeCode here}.
         class Write; end
 
         # Arguments to {Google::Spanner::V1::Mutation#delete delete} operations.
@@ -79,10 +78,9 @@ module Google
         #     Required. The table whose rows will be deleted.
         # @!attribute [rw] key_set
         #   @return [Google::Spanner::V1::KeySet]
-        #     Required. The primary keys of the rows within
-        #     {Google::Spanner::V1::Mutation::Delete#table table} to delete. Delete is
-        #     idempotent. The transaction will succeed even if some or all rows do not
-        #     exist.
+        #     Required. The primary keys of the rows within {Google::Spanner::V1::Mutation::Delete#table table} to delete.
+        #     Delete is idempotent. The transaction will succeed even if some or all
+        #     rows do not exist.
         class Delete; end
       end
     end

data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/query_plan.rb

@@ -16,19 +16,17 @@
 module Google
   module Spanner
     module V1
-      # Node information for nodes appearing in a
-      # {Google::Spanner::V1::QueryPlan#plan_nodes QueryPlan#plan_nodes}.
+      # Node information for nodes appearing in a {Google::Spanner::V1::QueryPlan#plan_nodes QueryPlan#plan_nodes}.
       # @!attribute [rw] index
       #   @return [Integer]
-      #     The `PlanNode`'s index in [node
-      #     list][google.spanner.v1.QueryPlan.plan_nodes].
+      #     The `PlanNode`'s index in {Google::Spanner::V1::QueryPlan#plan_nodes node list}.
       # @!attribute [rw] kind
       #   @return [Google::Spanner::V1::PlanNode::Kind]
       #     Used to determine the type of node. May be needed for visualizing
       #     different kinds of nodes differently. For example, If the node is a
-      #     {Google::Spanner::V1::PlanNode::Kind::SCALAR SCALAR} node, it will have a
-      #     condensed representation which can be used to directly embed a description
-      #     of the node in its parent.
+      #     {Google::Spanner::V1::PlanNode::Kind::SCALAR SCALAR} node, it will have a condensed representation
+      #     which can be used to directly embed a description of the node in its
+      #     parent.
       # @!attribute [rw] display_name
       #   @return [String]
       #     The display name for the node.
@@ -37,8 +35,7 @@ module Google
       #     List of child node `index`es and their relationship to this parent.
       # @!attribute [rw] short_representation
       #   @return [Google::Spanner::V1::PlanNode::ShortRepresentation]
-      #     Condensed representation for
-      #     {Google::Spanner::V1::PlanNode::Kind::SCALAR SCALAR} nodes.
+      #     Condensed representation for {Google::Spanner::V1::PlanNode::Kind::SCALAR SCALAR} nodes.
       # @!attribute [rw] metadata
       #   @return [Google::Protobuf::Struct]
       #     Attributes relevant to the node contained in a group of key-value pairs.
@@ -69,14 +66,14 @@ module Google
         #     with the output variable.
         # @!attribute [rw] variable
         #   @return [String]
-        #     Only present if the child node is
-        #     {Google::Spanner::V1::PlanNode::Kind::SCALAR SCALAR} and corresponds to an
-        #     output variable of the parent node. The field carries the name of the
-        #     output variable. For example, a `TableScan` operator that reads rows from
-        #     a table will have child links to the `SCALAR` nodes representing the
-        #     output variables created for each column that is read by the operator.
-        #     The corresponding `variable` fields will be set to the variable names
-        #     assigned to the columns.
+        #     Only present if the child node is {Google::Spanner::V1::PlanNode::Kind::SCALAR SCALAR} and corresponds
+        #     to an output variable of the parent node. The field carries the name of
+        #     the output variable.
+        #     For example, a `TableScan` operator that reads rows from a table will
+        #     have child links to the `SCALAR` nodes representing the output variables
+        #     created for each column that is read by the operator. The corresponding
+        #     `variable` fields will be set to the variable names assigned to the
+        #     columns.
         class ChildLink; end
 
         # Condensed representation of a node and its subtree. Only present for
@@ -93,8 +90,8 @@ module Google
         #     this node.
         class ShortRepresentation; end
 
-        # The kind of {Google::Spanner::V1::PlanNode PlanNode}. Distinguishes between
-        # the two different kinds of nodes that can appear in a query plan.
+        # The kind of {Google::Spanner::V1::PlanNode PlanNode}. Distinguishes between the two different kinds of
+        # nodes that can appear in a query plan.
         module Kind
           # Not specified.
           KIND_UNSPECIFIED = 0
@@ -116,8 +113,8 @@ module Google
       # @!attribute [rw] plan_nodes
       #   @return [Array<Google::Spanner::V1::PlanNode>]
       #     The nodes in the query plan. Plan nodes are returned in pre-order starting
-      #     with the plan root. Each {Google::Spanner::V1::PlanNode PlanNode}'s `id`
-      #     corresponds to its index in `plan_nodes`.
+      #     with the plan root. Each {Google::Spanner::V1::PlanNode PlanNode}'s `id` corresponds to its index in
+      #     `plan_nodes`.
       class QueryPlan; end
     end
   end

data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/result_set.rb

@@ -24,10 +24,11 @@ module Google
       # @!attribute [rw] rows
       #   @return [Array<Google::Protobuf::ListValue>]
       #     Each element in `rows` is a row whose format is defined by
-      #     {Google::Spanner::V1::ResultSetMetadata#row_type metadata::row_type}. The ith
-      #     element in each row matches the ith field in
-      #     {Google::Spanner::V1::ResultSetMetadata#row_type metadata::row_type}. Elements
-      #     are encoded based on type as described {Google::Spanner::V1::TypeCode here}.
+      #     {Google::Spanner::V1::ResultSetMetadata#row_type metadata::row_type}. The ith element
+      #     in each row matches the ith field in
+      #     {Google::Spanner::V1::ResultSetMetadata#row_type metadata::row_type}. Elements are
+      #     encoded based on type as described
+      #     {Google::Spanner::V1::TypeCode here}.
       # @!attribute [rw] stats
       #   @return [Google::Spanner::V1::ResultSetStats]
       #     Query plan and execution statistics for the SQL statement that
@@ -35,8 +36,7 @@ module Google
       #     {Google::Spanner::V1::ExecuteSqlRequest#query_mode ExecuteSqlRequest#query_mode}.
       #     DML statements always produce stats containing the number of rows
       #     modified, unless executed using the
-      #     {Google::Spanner::V1::ExecuteSqlRequest::QueryMode::PLAN ExecuteSqlRequest::QueryMode::PLAN}
-      #     {Google::Spanner::V1::ExecuteSqlRequest#query_mode ExecuteSqlRequest#query_mode}.
+      #     {Google::Spanner::V1::ExecuteSqlRequest::QueryMode::PLAN ExecuteSqlRequest::QueryMode::PLAN} {Google::Spanner::V1::ExecuteSqlRequest#query_mode ExecuteSqlRequest#query_mode}.
       #     Other fields may or may not be populated, based on the
       #     {Google::Spanner::V1::ExecuteSqlRequest#query_mode ExecuteSqlRequest#query_mode}.
       class ResultSet; end
@@ -61,10 +61,9 @@ module Google
       #
       #     It is possible that the last value in values is "chunked",
       #     meaning that the rest of the value is sent in subsequent
-      #     `PartialResultSet`(s). This is denoted by the
-      #     {Google::Spanner::V1::PartialResultSet#chunked_value chunked_value} field.
-      #     Two or more chunked values can be merged to form a complete value as
-      #     follows:
+      #     `PartialResultSet`(s). This is denoted by the {Google::Spanner::V1::PartialResultSet#chunked_value chunked_value}
+      #     field. Two or more chunked values can be merged to form a
+      #     complete value as follows:
       #
       #     * `bool/number/null`: cannot be chunked
       #       * `string`: concatenate the strings
@@ -126,10 +125,9 @@ module Google
       #     field value `"World" = "W" + "orl" + "d"`.
       # @!attribute [rw] chunked_value
       #   @return [true, false]
-      #     If true, then the final value in
-      #     {Google::Spanner::V1::PartialResultSet#values values} is chunked, and must be
-      #     combined with more values from subsequent `PartialResultSet`s to obtain a
-      #     complete field value.
+      #     If true, then the final value in {Google::Spanner::V1::PartialResultSet#values values} is chunked, and must
+      #     be combined with more values from subsequent `PartialResultSet`s
+      #     to obtain a complete field value.
       # @!attribute [rw] resume_token
       #   @return [String]
       #     Streaming calls might be interrupted for a variety of reasons, such
@@ -141,13 +139,13 @@ module Google
       #   @return [Google::Spanner::V1::ResultSetStats]
       #     Query plan and execution statistics for the statement that produced this
       #     streaming result set. These can be requested by setting
-      #     {Google::Spanner::V1::ExecuteSqlRequest#query_mode ExecuteSqlRequest#query_mode}
-      #     and are sent only once with the last response in the stream. This field
-      #     will also be present in the last response for DML statements.
+      #     {Google::Spanner::V1::ExecuteSqlRequest#query_mode ExecuteSqlRequest#query_mode} and are sent
+      #     only once with the last response in the stream.
+      #     This field will also be present in the last response for DML
+      #     statements.
       class PartialResultSet; end
 
-      # Metadata about a {Google::Spanner::V1::ResultSet ResultSet} or
-      # {Google::Spanner::V1::PartialResultSet PartialResultSet}.
+      # Metadata about a {Google::Spanner::V1::ResultSet ResultSet} or {Google::Spanner::V1::PartialResultSet PartialResultSet}.
       # @!attribute [rw] row_type
       #   @return [Google::Spanner::V1::StructType]
       #     Indicates the field names and types for the rows in the result
@@ -164,12 +162,10 @@ module Google
       #     information about the new transaction is yielded here.
       class ResultSetMetadata; end
 
-      # Additional statistics about a {Google::Spanner::V1::ResultSet ResultSet} or
-      # {Google::Spanner::V1::PartialResultSet PartialResultSet}.
+      # Additional statistics about a {Google::Spanner::V1::ResultSet ResultSet} or {Google::Spanner::V1::PartialResultSet PartialResultSet}.
       # @!attribute [rw] query_plan
       #   @return [Google::Spanner::V1::QueryPlan]
-      #     {Google::Spanner::V1::QueryPlan QueryPlan} for the query associated with this
-      #     result.
+      #     {Google::Spanner::V1::QueryPlan QueryPlan} for the query associated with this result.
       # @!attribute [rw] query_stats
       #   @return [Google::Protobuf::Struct]
       #     Aggregated statistics from the execution of the query. Only present when

data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/spanner.rb

@@ -138,30 +138,28 @@ module Google
       #     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.
+      #     Standard DML statements require a read-write transaction. To protect
+      #     against replays, single-use transactions are not supported.  The caller
+      #     must either supply an existing transaction ID or begin a new transaction.
       #
-      #     Partitioned DML requires an existing PartitionedDml transaction ID.
+      #     Partitioned DML requires an existing Partitioned DML transaction ID.
       # @!attribute [rw] sql
       #   @return [String]
       #     Required. The SQL string.
       # @!attribute [rw] params
       #   @return [Google::Protobuf::Struct]
-      #     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.
+      #     Parameter names and values that bind to placeholders in the SQL string.
+      #
+      #     A parameter placeholder consists of the `@` character followed by the
+      #     parameter name (for example, `@firstName`). Parameter names can contain
+      #     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"`
       #
-      #     It is an error to execute an SQL statement with unbound parameters.
+      #     `"WHERE id > @msg_id AND id < @msg_id + 100"`
       #
-      #     Parameter values are specified using `params`, which is a JSON
-      #     object whose keys are parameter names, and whose values are the
-      #     corresponding parameter values.
+      #     It is an error to execute a SQL statement with unbound parameters.
       # @!attribute [rw] param_types
       #   @return [Hash{String => Google::Spanner::V1::Type}]
       #     It is not always possible for Cloud Spanner to infer the right SQL type
@@ -197,7 +195,7 @@ module Google
       #     PartitionQueryRequest message used to create this partition_token.
       # @!attribute [rw] seqno
       #   @return [Integer]
-      #     A per-transaction sequence number used to identify this request. This
+      #     A per-transaction sequence number used to identify this request. This field
       #     makes each request idempotent such that if the request is received multiple
       #     times, at most one will succeed.
       #
@@ -223,29 +221,35 @@ module Google
         end
       end
 
-      # The request for {Google::Spanner::V1::Spanner::ExecuteBatchDml ExecuteBatchDml}
+      # The request for {Google::Spanner::V1::Spanner::ExecuteBatchDml ExecuteBatchDml}.
       # @!attribute [rw] session
       #   @return [String]
       #     Required. The session in which the DML statements should be performed.
       # @!attribute [rw] transaction
       #   @return [Google::Spanner::V1::TransactionSelector]
-      #     The transaction to use. A ReadWrite transaction is required. Single-use
-      #     transactions are not supported (to avoid replay).  The caller must either
-      #     supply an existing transaction ID or begin a new transaction.
+      #     Required. The transaction to use. Must be a read-write transaction.
+      #
+      #     To protect against replays, single-use transactions are not supported. The
+      #     caller must either supply an existing transaction ID or begin a new
+      #     transaction.
       # @!attribute [rw] statements
       #   @return [Array<Google::Spanner::V1::ExecuteBatchDmlRequest::Statement>]
-      #     The list of statements to execute in this batch. Statements are executed
-      #     serially, such that the effects of statement i are visible to statement
-      #     i+1. Each statement must be a DML statement. Execution will stop at the
-      #     first failed statement; the remaining statements will not run.
+      #     Required. The list of statements to execute in this batch. Statements are
+      #     executed serially, such that the effects of statement `i` are visible to
+      #     statement `i+1`. Each statement must be a DML statement. Execution stops at
+      #     the first failed statement; the remaining statements are not executed.
       #
-      #     REQUIRES: statements_size() > 0.
+      #     Callers must provide at least one statement.
       # @!attribute [rw] seqno
       #   @return [Integer]
-      #     A per-transaction sequence number used to identify this request. This is
-      #     used in the same space as the seqno in
-      #     {Spanner::ExecuteSqlRequest ExecuteSqlRequest}. See more details
-      #     in {Spanner::ExecuteSqlRequest ExecuteSqlRequest}.
+      #     Required. A per-transaction sequence number used to identify this request.
+      #     This field 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.
       class ExecuteBatchDmlRequest
         # A single DML statement.
         # @!attribute [rw] sql
@@ -253,20 +257,18 @@ module Google
         #     Required. The DML string.
         # @!attribute [rw] params
         #   @return [Google::Protobuf::Struct]
-        #     The DML 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.
+        #     Parameter names and values that bind to placeholders in the DML string.
+        #
+        #     A parameter placeholder consists of the `@` character followed by the
+        #     parameter name (for example, `@firstName`). Parameter names can contain
+        #     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"`
         #
-        #     It is an error to execute an SQL statement with unbound parameters.
+        #     `"WHERE id > @msg_id AND id < @msg_id + 100"`
         #
-        #     Parameter values are specified using `params`, which is a JSON
-        #     object whose keys are parameter names, and whose values are the
-        #     corresponding parameter values.
+        #     It is an error to execute a SQL statement with unbound parameters.
         # @!attribute [rw] param_types
         #   @return [Hash{String => Google::Spanner::V1::Type}]
         #     It is not always possible for Cloud Spanner to infer the right SQL type
@@ -284,39 +286,49 @@ module Google
 
       # The response for
       # {Google::Spanner::V1::Spanner::ExecuteBatchDml ExecuteBatchDml}. Contains a list
-      # of {Google::Spanner::V1::ResultSet ResultSet}, one for each DML statement that
-      # has successfully executed. If a statement fails, the error is returned as
-      # part of the response payload. Clients can determine whether all DML
-      # statements have run successfully, or if a statement failed, using one of the
-      # following approaches:
-      #
-      #   1. Check if 'status' field is OkStatus.
-      #   2. Check if result_sets_size() equals the number of statements in
-      #      {Spanner::ExecuteBatchDmlRequest ExecuteBatchDmlRequest}.
-      #
-      # Example 1: A request with 5 DML statements, all executed successfully.
-      # Result: A response with 5 ResultSets, one for each statement in the same
-      # order, and an OK status.
-      #
-      # Example 2: A request with 5 DML statements. The 3rd statement has a syntax
-      # error.
-      # Result: A response with 2 ResultSets, for the first 2 statements that
-      # run successfully, and a syntax error (INVALID_ARGUMENT) status. From
-      # result_set_size() client can determine that the 3rd statement has failed.
+      # of {Google::Spanner::V1::ResultSet ResultSet} messages, one for each DML
+      # statement that has successfully executed, in the same order as the statements
+      # in the request. If a statement fails, the status in the response body
+      # identifies the cause of the failure.
+      #
+      # To check for DML statements that failed, use the following approach:
+      #
+      # 1. Check the status in the response message. The
+      # {Google::Rpc::Code} enum
+      #    value `OK` indicates that all statements were executed successfully.
+      # 2. If the status was not `OK`, check the number of result sets in the
+      #    response. If the response contains `N`
+      #    {Google::Spanner::V1::ResultSet ResultSet} messages, then statement `N+1` in
+      #    the request failed.
+      #
+      # Example 1:
+      #
+      # * Request: 5 DML statements, all executed successfully.
+      # * Response: 5 {Google::Spanner::V1::ResultSet ResultSet} messages, with the
+      #   status `OK`.
+      #
+      # Example 2:
+      #
+      # * Request: 5 DML statements. The third statement has a syntax error.
+      # * Response: 2 {Google::Spanner::V1::ResultSet ResultSet} messages, and a syntax
+      #   error (`INVALID_ARGUMENT`)
+      #   status. The number of {Google::Spanner::V1::ResultSet ResultSet} messages
+      #   indicates that the third statement failed, and the fourth and fifth
+      #   statements were not executed.
       # @!attribute [rw] result_sets
       #   @return [Array<Google::Spanner::V1::ResultSet>]
-      #     ResultSets, one for each statement in the request that ran successfully, in
-      #     the same order as the statements in the request. Each
-      #     {Google::Spanner::V1::ResultSet ResultSet} will not contain any rows. The
-      #     {Google::Spanner::V1::ResultSetStats ResultSetStats} in each
-      #     {Google::Spanner::V1::ResultSet ResultSet} will contain the number of rows
+      #     One {Google::Spanner::V1::ResultSet ResultSet} for each statement in the
+      #     request that ran successfully, in the same order as the statements in the
+      #     request. Each {Google::Spanner::V1::ResultSet ResultSet} does not contain any
+      #     rows. The {Google::Spanner::V1::ResultSetStats ResultSetStats} in each
+      #     {Google::Spanner::V1::ResultSet ResultSet} contain the number of rows
       #     modified by the statement.
       #
-      #     Only the first ResultSet in the response contains a valid
-      #     {Google::Spanner::V1::ResultSetMetadata ResultSetMetadata}.
+      #     Only the first {Google::Spanner::V1::ResultSet ResultSet} in the response
+      #     contains valid {Google::Spanner::V1::ResultSetMetadata ResultSetMetadata}.
       # @!attribute [rw] status
       #   @return [Google::Rpc::Status]
-      #     If all DML statements are executed successfully, status will be OK.
+      #     If all DML statements are executed successfully, the status is `OK`.
       #     Otherwise, the error status of the first failed statement.
       class ExecuteBatchDmlResponse; end
 
@@ -352,8 +364,8 @@ module Google
       #     transactions are not.
       # @!attribute [rw] sql
       #   @return [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
+      #     Required. 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
@@ -365,20 +377,18 @@ module Google
       #     PartitionedDml transaction for large, partition-friendly DML operations.
       # @!attribute [rw] params
       #   @return [Google::Protobuf::Struct]
-      #     The SQL query 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.
+      #     Parameter names and values that bind to placeholders in the SQL string.
+      #
+      #     A parameter placeholder consists of the `@` character followed by the
+      #     parameter name (for example, `@firstName`). Parameter names can contain
+      #     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"`
       #
-      #     It is an error to execute an SQL query with unbound parameters.
+      #     `"WHERE id > @msg_id AND id < @msg_id + 100"`
       #
-      #     Parameter values are specified using `params`, which is a JSON
-      #     object whose keys are parameter names, and whose values are the
-      #     corresponding parameter values.
+      #     It is an error to execute a SQL statement with unbound parameters.
       # @!attribute [rw] param_types
       #   @return [Hash{String => Google::Spanner::V1::Type}]
       #     It is not always possible for Cloud Spanner to infer the right SQL type
@@ -476,8 +486,8 @@ module Google
       #     information.
       # @!attribute [rw] columns
       #   @return [Array<String>]
-      #     The columns of {Google::Spanner::V1::ReadRequest#table table} to be returned
-      #     for each row matching this request.
+      #     Required. The columns of {Google::Spanner::V1::ReadRequest#table table} to be
+      #     returned for each row matching this request.
       # @!attribute [rw] key_set
       #   @return [Google::Spanner::V1::KeySet]
       #     Required. `key_set` identifies the rows to be yielded. `key_set` names the