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
googleapis · Mar 4, 2022 · 4657e2f · 4657e2f
1 parent e0708ef
commit 4657e2f
Show file tree

Hide file tree

Showing 5 changed files with 34 additions and 2 deletions.
diff --git a/google/cloud/bigquery_storage_v1/services/big_query_write/async_client.py b/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
 

diff --git a/google/cloud/bigquery_storage_v1/services/big_query_write/client.py b/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
 

diff --git a/google/cloud/bigquery_storage_v1/services/big_query_write/transports/grpc.py b/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]:

diff --git a/google/cloud/bigquery_storage_v1/services/big_query_write/transports/grpc_asyncio.py b/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]]:

diff --git a/google/cloud/bigquery_storage_v1/types/storage.py b/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,)