docs: clarify size limitations for AppendRowsRequest

Google APIs · copybara-github · commit d33b3fa0897c · 2022-07-27T09:10:34.000-07:00
chore: add preferred_min_stream_count to CreateReadSessionRequest
chore: add write_stream to AppendRowsResponse

PiperOrigin-RevId: 463602530
diff --git a/google/cloud/bigquery/storage/v1/bigquerystorage_v1.yaml b/google/cloud/bigquery/storage/v1/bigquerystorage_v1.yaml
@@ -17,8 +17,8 @@ backend:
     deadline: 120.0
   - selector: 'google.cloud.bigquery.storage.v1.BigQueryWrite.*'
     deadline: 120.0
-  - selector: google.cloud.bigquery.storage.v1.BigQueryWrite.AppendRows
-    deadline: 21600.0
+  - selector: google.cloud.bigquery.storage.v1.BigQueryWrite.CreateWriteStream
+    deadline: 600.0
 
 authentication:
   rules:
diff --git a/google/cloud/bigquery/storage/v1/storage.proto b/google/cloud/bigquery/storage/v1/storage.proto
@@ -256,6 +256,16 @@ message CreateReadSessionRequest {
   // determine an upper bound OR set this a size for the maximum "units of work"
   // it can gracefully handle.
   int32 max_stream_count = 3;
+
+  // The minimum preferred stream count. This parameter can be used to inform
+  // the service that there is a desired lower bound on the number of streams.
+  // This is typically a target parallelism of the client (e.g. a Spark
+  // cluster with N-workers would set this to a low multiple of N to ensure
+  // good cluster utilization).
+  //
+  // The system will make a best effort to provide at least this number of
+  // streams, but in some cases might provide less.
+  int32 preferred_min_stream_count = 4;
 }
 
 // Request message for `ReadRows`.
@@ -395,6 +405,9 @@ message CreateWriteStreamRequest {
 // 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.
+//
+// The size of a single AppendRowsRequest must be less than 10 MB in size.
+// Requests larger than this return an error, typically `INVALID_ARGUMENT`.
 message AppendRowsRequest {
   // ProtoData contains the data rows and schema when constructing append
   // requests.
@@ -495,6 +508,10 @@ message AppendRowsResponse {
   // appended. The API will return row level error info, so that the caller can
   // remove the bad rows and retry the request.
   repeated RowError row_errors = 4;
+
+  // The target of the append operation. Matches the write_stream in the
+  // corresponding request.
+  string write_stream = 5;
 }
 
 // Request message for `GetWriteStreamRequest`.
