storage.rb in google-cloud-bigquery-storage-v1-0.21.0

- old
+ new

@@ -188,30 +188,51 @@
             extend ::Google::Protobuf::MessageExts::ClassMethods
           end
 
           # Request message for `AppendRows`.
           #
-          # Due to the nature of AppendRows being a bidirectional streaming RPC, certain
-          # parts of the AppendRowsRequest need only be specified for the first request
-          # sent each time the gRPC network connection is opened/reopened.
+          # Because AppendRows is a bidirectional streaming RPC, certain parts of the
+          # AppendRowsRequest need only be specified for the first request before
+          # switching table destinations. You can also switch table destinations within
+          # the same connection for the default stream.
           #
           # The size of a single AppendRowsRequest must be less than 10 MB in size.
           # Requests larger than this return an error, typically `INVALID_ARGUMENT`.
           # @!attribute [rw] write_stream
           #   @return [::String]
-          #     Required. The write_stream identifies the target of the append operation,
-          #     and only needs to be specified as part of the first request on the gRPC
-          #     connection. If provided for subsequent requests, it must match the value of
-          #     the first request.
+          #     Required. The write_stream identifies the append operation. It must be
+          #     provided in the following scenarios:
           #
+          #     * In the first request to an AppendRows connection.
+          #
+          #     * In all subsequent requests to an AppendRows connection, if you use the
+          #     same connection to write to multiple tables or change the input schema for
+          #     default streams.
+          #
           #     For explicitly created write streams, the format is:
           #
           #     * `projects/{project}/datasets/{dataset}/tables/{table}/streams/{id}`
           #
           #     For the special default stream, the format is:
           #
           #     * `projects/{project}/datasets/{dataset}/tables/{table}/streams/_default`.
+          #
+          #     An example of a possible sequence of requests with write_stream fields
+          #     within a single connection:
+          #
+          #     * r1: \\{write_stream: stream_name_1}
+          #
+          #     * r2: \\{write_stream: /*omit*/}
+          #
+          #     * r3: \\{write_stream: /*omit*/}
+          #
+          #     * r4: \\{write_stream: stream_name_2}
+          #
+          #     * r5: \\{write_stream: stream_name_2}
+          #
+          #     The destination changed in request_4, so the write_stream field must be
+          #     populated in all subsequent requests in this stream.
           # @!attribute [rw] offset
           #   @return [::Google::Protobuf::Int64Value]
           #     If present, the write is only performed if the next append offset is same
           #     as the provided value. If not present, the write is performed at the
           #     current end of stream. Specifying a value for this field is not allowed
@@ -249,13 +270,18 @@
 
             # ProtoData contains the data rows and schema when constructing append
             # requests.
             # @!attribute [rw] writer_schema
             #   @return [::Google::Cloud::Bigquery::Storage::V1::ProtoSchema]
-            #     Proto schema used to serialize the data.  This value only needs to be
-            #     provided as part of the first request on a gRPC network connection,
-            #     and will be ignored for subsequent requests on the connection.
+            #     The protocol buffer schema used to serialize the data. Provide this value
+            #     whenever:
+            #
+            #     * You send the first request of an RPC connection.
+            #
+            #     * You change the input schema.
+            #
+            #     * You specify a new destination table.
             # @!attribute [rw] rows
             #   @return [::Google::Cloud::Bigquery::Storage::V1::ProtoRows]
             #     Serialized row data in protobuf message format.
             #     Currently, the backend expects the serialized rows to adhere to
             #     proto2 semantics when appending rows, particularly with respect to
@@ -272,13 +298,12 @@
             class MissingValueInterpretationsEntry
               include ::Google::Protobuf::MessageExts
               extend ::Google::Protobuf::MessageExts::ClassMethods
             end
 
-            # An enum to indicate how to interpret missing values. Missing values are
-            # fields present in user schema but missing in rows. A missing value can
-            # represent a NULL or a column default value defined in BigQuery table
-            # schema.
+            # An enum to indicate how to interpret missing values of fields that are
+            # present in user schema but missing in rows. A missing value can represent a
+            # NULL or a column default value defined in BigQuery table schema.
             module MissingValueInterpretation
               # Invalid missing value interpretation. Requests with this value will be
               # rejected.
               MISSING_VALUE_INTERPRETATION_UNSPECIFIED = 0
 