docs: improve documentation for write client (#403)

- [ ] Regenerate this pull request now.

feat: update default timeout/retry information
feat: update parent annotation for BatchCommitWriteStreamsRequest
feat: expose additional StorageError enum values

PiperOrigin-RevId: 431973595

Source-Link: googleapis/googleapis@25d691b

Source-Link: googleapis/googleapis-gen@0ca2187
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMGNhMjE4NzlhZTMxMzZhMmQ3MWZhODI0YjQ5ZGZhZjhhMGFlMGYyZSJ9

Author: gcf-owl-bot[bot]

packages/google-cloud-bigquery-storage/google/cloud/bigquery_storage_v1/services/big_query_write/async_client.py

@@ -381,6 +381,13 @@ def append_rows(
            rpc), and the stream is explicitly committed via the
            ``BatchCommitWriteStreams`` rpc.
 
+        Note: For users coding against the gRPC api directly, it may be
+        necessary to supply the x-goog-request-params system parameter
+        with ``write_stream=<full_write_stream_name>``.
+
+        More information about system parameters:
+        https://cloud.google.com/apis/docs/system-parameters
+
 
         .. code-block:: python
 

packages/google-cloud-bigquery-storage/google/cloud/bigquery_storage_v1/services/big_query_write/client.py

@@ -570,6 +570,13 @@ def append_rows(
            rpc), and the stream is explicitly committed via the
            ``BatchCommitWriteStreams`` rpc.
 
+        Note: For users coding against the gRPC api directly, it may be
+        necessary to supply the x-goog-request-params system parameter
+        with ``write_stream=<full_write_stream_name>``.
+
+        More information about system parameters:
+        https://cloud.google.com/apis/docs/system-parameters
+
 
         .. code-block:: python
 

packages/google-cloud-bigquery-storage/google/cloud/bigquery_storage_v1/services/big_query_write/transports/grpc.py

@@ -305,6 +305,13 @@ def append_rows(
            rpc), and the stream is explicitly committed via the
            ``BatchCommitWriteStreams`` rpc.
 
+        Note: For users coding against the gRPC api directly, it may be
+        necessary to supply the x-goog-request-params system parameter
+        with ``write_stream=<full_write_stream_name>``.
+
+        More information about system parameters:
+        https://cloud.google.com/apis/docs/system-parameters
+
         Returns:
             Callable[[~.AppendRowsRequest],
                     ~.AppendRowsResponse]:

packages/google-cloud-bigquery-storage/google/cloud/bigquery_storage_v1/services/big_query_write/transports/grpc_asyncio.py

@@ -307,6 +307,13 @@ def append_rows(
            rpc), and the stream is explicitly committed via the
            ``BatchCommitWriteStreams`` rpc.
 
+        Note: For users coding against the gRPC api directly, it may be
+        necessary to supply the x-goog-request-params system parameter
+        with ``write_stream=<full_write_stream_name>``.
+
+        More information about system parameters:
+        https://cloud.google.com/apis/docs/system-parameters
+
         Returns:
             Callable[[~.AppendRowsRequest],
                     Awaitable[~.AppendRowsResponse]]:

packages/google-cloud-bigquery-storage/google/cloud/bigquery_storage_v1/types/storage.py

@@ -280,10 +280,12 @@ class AppendRowsRequest(proto.Message):
             request.
 
             For explicitly created write streams, the format is:
-            ``projects/{project}/datasets/{dataset}/tables/{table}/streams/{id}``
+
+            -  ``projects/{project}/datasets/{dataset}/tables/{table}/streams/{id}``
 
             For the special default stream, the format is:
-            ``projects/{project}/datasets/{dataset}/tables/{table}/_default``.
+
+            -  ``projects/{project}/datasets/{dataset}/tables/{table}/streams/_default``.
         offset (google.protobuf.wrappers_pb2.Int64Value):
             If present, the write is only performed if the next append
             offset is same as the provided value. If not present, the
@@ -529,6 +531,8 @@ class StorageErrorCode(proto.Enum):
         INVALID_STREAM_STATE = 5
         STREAM_FINALIZED = 6
         SCHEMA_MISMATCH_EXTRA_FIELDS = 7
+        OFFSET_ALREADY_EXISTS = 8
+        OFFSET_OUT_OF_RANGE = 9
 
     code = proto.Field(proto.ENUM, number=1, enum=StorageErrorCode,)
     entity = proto.Field(proto.STRING, number=2,)