AppendRowsFuture(
manager: google.cloud.bigquery_storage_v1beta2.writer.AppendRowsStream,
)Encapsulation of the asynchronous execution of an action.
This object is returned from long-running BigQuery Storage API calls, and is the interface to determine the status of those calls.
This object should not be created directly, but is returned by other methods in this library.
Methods
add_done_callback
add_done_callback(fn)Add a callback to be executed when the operation is complete.
If the operation is not already complete, this will start a helper thread to poll for the status of the operation in the background.
| Parameter | |
|---|---|
| Name | Description |
fn |
Callable[Future]
The callback to execute when the operation is complete. |
cancel
cancel()Stops pulling messages and shutdowns the background thread consuming messages.
The method does not block, it just triggers the shutdown and returns
immediately. To block until the background stream is terminated, call
result() after cancelling the future.
cancelled
cancelled()| Returns | |
|---|---|
| Type | Description |
bool | True if the write stream has been cancelled. |
done
done(retry: Optional[google.api_core.retry.Retry] = None)Check the status of the future.
exception
exception(timeout=<object object>)Get the exception from the operation, blocking if necessary.
See the documentation for the result method for details on how
this method operates, as both result and this method rely on the
exact same polling logic. The only difference is that this method does
not accept retry and polling arguments but relies on the default ones
instead.
| Parameter | |
|---|---|
| Name | Description |
timeout |
int
How long to wait for the operation to complete. |
| Returns | |
|---|---|
| Type | Description |
Optional[google.api_core.GoogleAPICallError] | The operation's error. |
result
result(timeout=<object object>, retry=None, polling=None)Get the result of the operation.
This method will poll for operation status periodically, blocking if
necessary. If you just want to make sure that this method does not block
for more than X seconds and you do not care about the nitty-gritty of
how this method operates, just call it with result(timeout=X). The
other parameters are for advanced use only.
Every call to this method is controlled by the following three
parameters, each of which has a specific, distinct role, even though all three
may look very similar: timeout, retry and polling. In most
cases users do not need to specify any custom values for any of these
parameters and may simply rely on default ones instead.
If you choose to specify custom parameters, please make sure you've read the documentation below carefully.
First, please check google.api_core.retry.Retry
class documentation for the proper definition of timeout and deadline
terms and for the definition the three different types of timeouts.
This class operates in terms of Retry Timeout and Polling Timeout. It
does not let customizing RPC timeout and the user is expected to rely on
default behavior for it.
The roles of each argument of this method are as follows:
timeout (int): (Optional) The Polling Timeout as defined in
google.api_core.retry.Retry. If the operation does not complete
within this timeout an exception will be thrown. This parameter affects
neither Retry Timeout nor RPC Timeout.
retry (google.api_core.retry.Retry): (Optional) How to retry the
polling RPC. The retry.timeout property of this parameter is the
Retry Timeout as defined in google.api_core.retry.Retry.
This parameter defines ONLY how the polling RPC call is retried
(i.e. what to do if the RPC we used for polling returned an error). It
does NOT define how the polling is done (i.e. how frequently and for
how long to call the polling RPC); use the polling parameter for that.
If a polling RPC throws and error and retrying it fails, the whole
future fails with the corresponding exception. If you want to tune which
server response error codes are not fatal for operation polling, use this
parameter to control that (retry.predicate in particular).
polling (google.api_core.retry.Retry): (Optional) How often and
for how long to call the polling RPC periodically (i.e. what to do if
a polling rpc returned successfully but its returned result indicates
that the long running operation is not completed yet, so we need to
check it again at some point in future). This parameter does NOT define
how to retry each individual polling RPC in case of an error; use the
retry parameter for that. The polling.timeout of this parameter
is Polling Timeout as defined in as defined in
google.api_core.retry.Retry.
For each of the arguments, there are also default values in place, which will be used if a user does not specify their own. The default values for the three parameters are not to be confused with the default values for the corresponding arguments in this method (those serve as "not set" markers for the resolution logic).
If timeout is provided (i.e.timeout is not _DEFAULT VALUE; note
the None value means "infinite timeout"), it will be used to control
the actual Polling Timeout. Otherwise, the polling.timeout value
will be used instead (see below for how the polling config itself
gets resolved). In other words, this parameter effectively overrides
the polling.timeout value if specified. This is so to preserve
backward compatibility.
If retry is provided (i.e. retry is not None) it will be used to
control retry behavior for the polling RPC and the retry.timeout
will determine the Retry Timeout. If not provided, the
polling RPC will be called with whichever default retry config was
specified for the polling RPC at the moment of the construction of the
polling RPC's client. For example, if the polling RPC is
operations_client.get_operation(), the retry parameter will be
controlling its retry behavior (not polling behavior) and, if not
specified, that specific method (operations_client.get_operation())
will be retried according to the default retry config provided during
creation of operations_client client instead. This argument exists
mainly for backward compatibility; users are very unlikely to ever need
to set this parameter explicitly.
If polling is provided (i.e. polling is not None), it will be used
to controll the overall polling behavior and polling.timeout will
controll Polling Timeout unless it is overridden by timeout parameter
as described above. If not provided, thepolling parameter specified
during construction of this future (the polling argument in the
constructor) will be used instead. Note: since the timeout argument may
override polling.timeout value, this parameter should be viewed as
coupled with the timeout parameter as described above.
| Parameters | |
|---|---|
| Name | Description |
timeout |
int
(Optional) How long (in seconds) to wait for the operation to complete. If None, wait indefinitely. |
retry |
google.api_core.retry.Retry
(Optional) How to retry the polling RPC. This defines ONLY how the polling RPC call is retried (i.e. what to do if the RPC we used for polling returned an error). It does NOT define how the polling is done (i.e. how frequently and for how long to call the polling RPC). |
polling |
google.api_core.retry.Retry
(Optional) How often and for how long to call polling RPC periodically. This parameter does NOT define how to retry each individual polling RPC call (use the |
| Exceptions | |
|---|---|
| Type | Description |
google.api_core.GoogleAPICallError | If the operation errors or if the timeout is reached before the operation completes. |
| Returns | |
|---|---|
| Type | Description |
google.protobuf.Message | The Operation's result. |
running
running()True if the operation is currently running.
set_exception
set_exception(exception)Set the result of the future as being the given exception.
Do not use this method, it should only be used internally by the library and its unit tests.
set_result
set_result(result)Set the return value of work associated with the future.
Do not use this method, it should only be used internally by the library and its unit tests.