docs: clarify size limitations for AppendRowsRequest (#474)

gcf-owl-bot[bot] · parthea · commit 898bd6135c4b · 2025-09-16T14:24:50.000Z
* docs: clarify size limitations for AppendRowsRequest chore: add preferred_min_stream_count to CreateReadSessionRequest chore: add write_stream to AppendRowsResponse PiperOrigin-RevId: 463602530 Source-Link: googleapis/googleapis@d33b3fa Source-Link: googleapis/googleapis-gen@90995f6 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiOTA5OTVmNjQzM2QwZWNkMjkwZjE4NjE2OGNlOTU3ZDZhMGRiOWM2OCJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
diff --git a/packages/google-cloud-bigquery-storage/google/cloud/bigquery_storage_v1/services/big_query_write/async_client.py b/packages/google-cloud-bigquery-storage/google/cloud/bigquery_storage_v1/services/big_query_write/async_client.py
@@ -431,6 +431,9 @@ def request_generator():
                 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`.
             retry (google.api_core.retry.Retry): Designation of what errors, if any,
                 should be retried.
             timeout (float): The timeout for this request.
diff --git a/packages/google-cloud-bigquery-storage/google/cloud/bigquery_storage_v1/services/big_query_write/client.py b/packages/google-cloud-bigquery-storage/google/cloud/bigquery_storage_v1/services/big_query_write/client.py
@@ -664,6 +664,9 @@ def request_generator():
                 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`.
             retry (google.api_core.retry.Retry): Designation of what errors, if any,
                 should be retried.
             timeout (float): The timeout for this request.
diff --git a/packages/google-cloud-bigquery-storage/google/cloud/bigquery_storage_v1/types/storage.py b/packages/google-cloud-bigquery-storage/google/cloud/bigquery_storage_v1/types/storage.py
@@ -73,6 +73,18 @@ class CreateReadSessionRequest(proto.Message):
             leave this unset to let the system to determine an upper
             bound OR set this a size for the maximum "units of work" it
             can gracefully handle.
+        preferred_min_stream_count (int):
+            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.
     """
 
     parent = proto.Field(
@@ -88,6 +100,10 @@ class CreateReadSessionRequest(proto.Message):
         proto.INT32,
         number=3,
     )
+    preferred_min_stream_count = proto.Field(
+        proto.INT32,
+        number=4,
+    )
 
 
 class ReadRowsRequest(proto.Message):
@@ -343,6 +359,10 @@ class AppendRowsRequest(proto.Message):
     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``.
+
 
     .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
 
@@ -478,6 +498,9 @@ class AppendRowsResponse(proto.Message):
             rows in the batch will be appended. The API will
             return row level error info, so that the caller
             can remove the bad rows and retry the request.
+        write_stream (str):
+            The target of the append operation. Matches the write_stream
+            in the corresponding request.
     """
 
     class AppendResult(proto.Message):
@@ -518,6 +541,10 @@ class AppendResult(proto.Message):
         number=4,
         message="RowError",
     )
+    write_stream = proto.Field(
+        proto.STRING,
+        number=5,
+    )
 
 
 class GetWriteStreamRequest(proto.Message):
diff --git a/packages/google-cloud-bigquery-storage/scripts/fixup_bigquery_storage_v1_keywords.py b/packages/google-cloud-bigquery-storage/scripts/fixup_bigquery_storage_v1_keywords.py
@@ -41,7 +41,7 @@ class bigquery_storageCallTransformer(cst.CSTTransformer):
     METHOD_TO_PARAMS: Dict[str, Tuple[str]] = {
         'append_rows': ('write_stream', 'offset', 'proto_rows', 'trace_id', ),
         'batch_commit_write_streams': ('parent', 'write_streams', ),
-        'create_read_session': ('parent', 'read_session', 'max_stream_count', ),
+        'create_read_session': ('parent', 'read_session', 'max_stream_count', 'preferred_min_stream_count', ),
         'create_write_stream': ('parent', 'write_stream', ),
         'finalize_write_stream': ('name', ),
         'flush_rows': ('write_stream', 'offset', ),
