Table Async
class google.cloud.bigtable.data._async.client.TableAsync(client: google.cloud.bigtable.data._async.client.BigtableDataClientAsync, instance_id: str, table_id: str, app_profile_id: typing.Optional[str] = None, *, default_read_rows_operation_timeout: float = 600, default_read_rows_attempt_timeout: float | None = 20, default_mutate_rows_operation_timeout: float = 600, default_mutate_rows_attempt_timeout: float | None = 60, default_operation_timeout: float = 60, default_attempt_timeout: float | None = 20, default_read_rows_retryable_errors: typing.Sequence[type[Exception]] = (<class 'google.api_core.exceptions.DeadlineExceeded'>, <class 'google.api_core.exceptions.ServiceUnavailable'>, <class 'google.api_core.exceptions.Aborted'>), default_mutate_rows_retryable_errors: typing.Sequence[type[Exception]] = (<class 'google.api_core.exceptions.DeadlineExceeded'>, <class 'google.api_core.exceptions.ServiceUnavailable'>), default_retryable_errors: typing.Sequence[type[Exception]] = (<class 'google.api_core.exceptions.DeadlineExceeded'>, <class 'google.api_core.exceptions.ServiceUnavailable'>))
Bases: object
Main Data API surface
Table object maintains table_id, and app_profile_id context, and passes them with each call
Initialize a Table instance
Must be created within an async context (running event loop)
Parameters
instance_id – The Bigtable instance ID to associate with this client. instance_id is combined with the client’s project to fully specify the instance
table_id – The ID of the table. table_id is combined with the instance_id and the client’s project to fully specify the table
app_profile_id – The app profile to associate with requests. https://cloud.google.com/bigtable/docs/app-profiles
default_read_rows_operation_timeout – The default timeout for read rows operations, in seconds. If not set, defaults to 600 seconds (10 minutes)
default_read_rows_attempt_timeout – The default timeout for individual read rows rpc requests, in seconds. If not set, defaults to 20 seconds
default_mutate_rows_operation_timeout – The default timeout for mutate rows operations, in seconds. If not set, defaults to 600 seconds (10 minutes)
default_mutate_rows_attempt_timeout – The default timeout for individual mutate rows rpc requests, in seconds. If not set, defaults to 60 seconds
default_operation_timeout – The default timeout for all other operations, in seconds. If not set, defaults to 60 seconds
default_attempt_timeout – The default timeout for all other individual rpc requests, in seconds. If not set, defaults to 20 seconds
default_read_rows_retryable_errors – a list of errors that will be retried if encountered during read_rows and related operations. Defaults to 4 (DeadlineExceeded), 14 (ServiceUnavailable), and 10 (Aborted)
default_mutate_rows_retryable_errors – a list of errors that will be retried if encountered during mutate_rows and related operations. Defaults to 4 (DeadlineExceeded) and 14 (ServiceUnavailable)
default_retryable_errors – a list of errors that will be retried if encountered during all other operations. Defaults to 4 (DeadlineExceeded) and 14 (ServiceUnavailable)
Raises
RuntimeError – if called outside of an async context (no running event loop)
async _aenter_()
Implement async context manager protocol
Ensure registration task has time to run, so that grpc channels will be warmed for the specified instance
async _aexit_(exc_type, exc_val, exc_tb)
Implement async context manager protocol
Unregister this instance with the client, so that grpc channels will no longer be warmed
async bulk_mutate_rows(mutation_entries: list[google.cloud.bigtable.data.mutations.RowMutationEntry], *, operation_timeout: float | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.MUTATE_ROWS, attempt_timeout: float | None | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.MUTATE_ROWS, retryable_errors: Union[Sequence[type[Exception]], google.cloud.bigtable.data._helpers.TABLE_DEFAULT] = TABLE_DEFAULT.MUTATE_ROWS)
Applies mutations for multiple rows in a single batched request.
Each individual RowMutationEntry is applied atomically, but separate entries may be applied in arbitrary order (even for entries targetting the same row) In total, the row_mutations can contain at most 100000 individual mutations across all entries
Idempotent entries (i.e., entries with mutations with explicit timestamps) will be retried on failure. Non-idempotent will not, and will reported in a raised exception group
Parameters
mutation_entries – the batches of mutations to apply Each entry will be applied atomically, but entries will be applied in arbitrary order
operation_timeout – the time budget for the entire operation, in seconds. Failed requests will be retried within the budget. Defaults to the Table’s default_mutate_rows_operation_timeout
attempt_timeout – the time budget for an individual network request, in seconds. If it takes longer than this time to complete, the request will be cancelled with a DeadlineExceeded exception, and a retry will be attempted. Defaults to the Table’s default_mutate_rows_attempt_timeout. If None, defaults to operation_timeout.
retryable_errors – a list of errors that will be retried if encountered. Defaults to the Table’s default_mutate_rows_retryable_errors
Raises
MutationsExceptionGroup – if one or more mutations fails Contains details about any failed entries in .exceptions
ValueError – if invalid arguments are provided
async check_and_mutate_row(row_key: str | bytes, predicate: google.cloud.bigtable.data.row_filters.RowFilter | None, *, true_case_mutations: Optional[Union[google.cloud.bigtable.data.mutations.Mutation, list[google.cloud.bigtable.data.mutations.Mutation]]] = None, false_case_mutations: Optional[Union[google.cloud.bigtable.data.mutations.Mutation, list[google.cloud.bigtable.data.mutations.Mutation]]] = None, operation_timeout: float | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.DEFAULT)
Mutates a row atomically based on the output of a predicate filter
Non-idempotent operation: will not be retried
Parameters
row_key – the key of the row to mutate
predicate – the filter to be applied to the contents of the specified row. Depending on whether or not any results are yielded, either true_case_mutations or false_case_mutations will be executed. If None, checks that the row contains any values at all.
true_case_mutations – Changes to be atomically applied to the specified row if predicate yields at least one cell when applied to row_key. Entries are applied in order, meaning that earlier mutations can be masked by later ones. Must contain at least one entry if false_case_mutations is empty, and at most 100000.
false_case_mutations – Changes to be atomically applied to the specified row if predicate_filter does not yield any cells when applied to row_key. Entries are applied in order, meaning that earlier mutations can be masked by later ones. Must contain at least one entry if true_case_mutations is empty, and at most 100000.
operation_timeout – the time budget for the entire operation, in seconds. Failed requests will not be retried. Defaults to the Table’s default_operation_timeout
Returns
bool indicating whether the predicate was true or false
Raises
google.api_core.exceptions.GoogleAPIError – exceptions from grpc call
async close()
Called to close the Table instance and release any resources held by it.
async mutate_row(row_key: str | bytes, mutations: list[google.cloud.bigtable.data.mutations.Mutation] | google.cloud.bigtable.data.mutations.Mutation, *, operation_timeout: float | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.DEFAULT, attempt_timeout: float | None | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.DEFAULT, retryable_errors: Union[Sequence[type[Exception]], google.cloud.bigtable.data._helpers.TABLE_DEFAULT] = TABLE_DEFAULT.DEFAULT)
Mutates a row atomically.
Cells already present in the row are left unchanged unless explicitly changed
by mutation
.
Idempotent operations (i.e, all mutations have an explicit timestamp) will be retried on server failure. Non-idempotent operations will not.
Parameters
row_key – the row to apply mutations to
mutations – the set of mutations to apply to the row
operation_timeout – the time budget for the entire operation, in seconds. Failed requests will be retried within the budget. Defaults to the Table’s default_operation_timeout
attempt_timeout – the time budget for an individual network request, in seconds. If it takes longer than this time to complete, the request will be cancelled with a DeadlineExceeded exception, and a retry will be attempted. Defaults to the Table’s default_attempt_timeout. If None, defaults to operation_timeout.
retryable_errors – a list of errors that will be retried if encountered. Only idempotent mutations will be retried. Defaults to the Table’s default_retryable_errors.
Raises
google.api_core.exceptions.DeadlineExceeded – raised after operation timeout will be chained with a RetryExceptionGroup containing all GoogleAPIError exceptions from any retries that failed
google.api_core.exceptions.GoogleAPIError – raised on non-idempotent operations that cannot be safely retried.
ValueError – if invalid arguments are provided
mutations_batcher(*, flush_interval: float | None = 5, flush_limit_mutation_count: int | None = 1000, flush_limit_bytes: int = 20971520, flow_control_max_mutation_count: int = 100000, flow_control_max_bytes: int = 104857600, batch_operation_timeout: float | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.MUTATE_ROWS, batch_attempt_timeout: float | None | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.MUTATE_ROWS, batch_retryable_errors: Union[Sequence[type[Exception]], google.cloud.bigtable.data._helpers.TABLE_DEFAULT] = TABLE_DEFAULT.MUTATE_ROWS)
Returns a new mutations batcher instance.
Can be used to iteratively add mutations that are flushed as a group, to avoid excess network calls
Parameters
flush_interval – Automatically flush every flush_interval seconds. If None, a table default will be used
flush_limit_mutation_count – Flush immediately after flush_limit_mutation_count mutations are added across all entries. If None, this limit is ignored.
flush_limit_bytes – Flush immediately after flush_limit_bytes bytes are added.
flow_control_max_mutation_count – Maximum number of inflight mutations.
flow_control_max_bytes – Maximum number of inflight bytes.
batch_operation_timeout – timeout for each mutate_rows operation, in seconds. Defaults to the Table’s default_mutate_rows_operation_timeout
batch_attempt_timeout – timeout for each individual request, in seconds. Defaults to the Table’s default_mutate_rows_attempt_timeout. If None, defaults to batch_operation_timeout.
batch_retryable_errors – a list of errors that will be retried if encountered. Defaults to the Table’s default_mutate_rows_retryable_errors.
Returns
a MutationsBatcherAsync context manager that can batch requests
Return type
async read_modify_write_row(row_key: str | bytes, rules: google.cloud.bigtable.data.read_modify_write_rules.ReadModifyWriteRule | list[google.cloud.bigtable.data.read_modify_write_rules.ReadModifyWriteRule], *, operation_timeout: float | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.DEFAULT)
Reads and modifies a row atomically according to input ReadModifyWriteRules, and returns the contents of all modified cells
The new value for the timestamp is the greater of the existing timestamp or the current server time.
Non-idempotent operation: will not be retried
Parameters
row_key – the key of the row to apply read/modify/write rules to
rules – A rule or set of rules to apply to the row. Rules are applied in order, meaning that earlier rules will affect the results of later ones.
operation_timeout – the time budget for the entire operation, in seconds. Failed requests will not be retried. Defaults to the Table’s default_operation_timeout.
Returns
a Row containing cell data that was modified as part of the operation
Return type
Raises
google.api_core.exceptions.GoogleAPIError – exceptions from grpc call
ValueError – if invalid arguments are provided
async read_row(row_key: str | bytes, *, row_filter: Optional[google.cloud.bigtable.data.row_filters.RowFilter] = None, operation_timeout: float | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.READ_ROWS, attempt_timeout: float | None | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.READ_ROWS, retryable_errors: Union[Sequence[type[Exception]], google.cloud.bigtable.data._helpers.TABLE_DEFAULT] = TABLE_DEFAULT.READ_ROWS)
Read a single row from the table, based on the specified key.
Failed requests within operation_timeout will be retried based on the retryable_errors list until operation_timeout is reached.
Parameters
query – contains details about which rows to return
operation_timeout – the time budget for the entire operation, in seconds. Failed requests will be retried within the budget. Defaults to the Table’s default_read_rows_operation_timeout
attempt_timeout – the time budget for an individual network request, in seconds. If it takes longer than this time to complete, the request will be cancelled with a DeadlineExceeded exception, and a retry will be attempted. Defaults to the Table’s default_read_rows_attempt_timeout. If None, defaults to operation_timeout.
retryable_errors – a list of errors that will be retried if encountered. Defaults to the Table’s default_read_rows_retryable_errors.
Returns
a Row object if the row exists, otherwise None
Return type
Row | None
Raises
google.api_core.exceptions.DeadlineExceeded – raised after operation timeout will be chained with a RetryExceptionGroup containing GoogleAPIError exceptions from any retries that failed
google.api_core.exceptions.GoogleAPIError – raised if the request encounters an unrecoverable error
async read_rows(query: google.cloud.bigtable.data.read_rows_query.ReadRowsQuery, *, operation_timeout: float | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.READ_ROWS, attempt_timeout: float | None | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.READ_ROWS, retryable_errors: Union[Sequence[type[Exception]], google.cloud.bigtable.data._helpers.TABLE_DEFAULT] = TABLE_DEFAULT.READ_ROWS)
Read a set of rows from the table, based on the specified query. Retruns results as a list of Row objects when the request is complete. For streamed results, use read_rows_stream.
Failed requests within operation_timeout will be retried based on the retryable_errors list until operation_timeout is reached.
Parameters
query – contains details about which rows to return
operation_timeout – the time budget for the entire operation, in seconds. Failed requests will be retried within the budget. Defaults to the Table’s default_read_rows_operation_timeout
attempt_timeout – the time budget for an individual network request, in seconds. If it takes longer than this time to complete, the request will be cancelled with a DeadlineExceeded exception, and a retry will be attempted. Defaults to the Table’s default_read_rows_attempt_timeout. If None, defaults to operation_timeout. If None, defaults to the Table’s default_read_rows_attempt_timeout, or the operation_timeout if that is also None.
retryable_errors – a list of errors that will be retried if encountered. Defaults to the Table’s default_read_rows_retryable_errors.
Returns
a list of Rows returned by the query
Return type
Raises
google.api_core.exceptions.DeadlineExceeded – raised after operation timeout will be chained with a RetryExceptionGroup containing GoogleAPIError exceptions from any retries that failed
google.api_core.exceptions.GoogleAPIError – raised if the request encounters an unrecoverable error
async read_rows_sharded(sharded_query: ShardedQuery, *, operation_timeout: float | TABLE_DEFAULT = TABLE_DEFAULT.READ_ROWS, attempt_timeout: float | None | TABLE_DEFAULT = TABLE_DEFAULT.READ_ROWS, retryable_errors: Sequence[type[Exception]] | TABLE_DEFAULT = TABLE_DEFAULT.READ_ROWS)
Runs a sharded query in parallel, then return the results in a single list. Results will be returned in the order of the input queries.
This function is intended to be run on the results on a query.shard() call. For example:
table_shard_keys = await table.sample_row_keys()
query = ReadRowsQuery(...)
shard_queries = query.shard(table_shard_keys)
results = await table.read_rows_sharded(shard_queries)
Parameters
sharded_query – a sharded query to execute
operation_timeout – the time budget for the entire operation, in seconds. Failed requests will be retried within the budget. Defaults to the Table’s default_read_rows_operation_timeout
attempt_timeout – the time budget for an individual network request, in seconds. If it takes longer than this time to complete, the request will be cancelled with a DeadlineExceeded exception, and a retry will be attempted. Defaults to the Table’s default_read_rows_attempt_timeout. If None, defaults to operation_timeout.
retryable_errors – a list of errors that will be retried if encountered. Defaults to the Table’s default_read_rows_retryable_errors.
Returns
a list of Rows returned by the query
Return type
Raises
ShardedReadRowsExceptionGroup – if any of the queries failed
ValueError – if the query_list is empty
async read_rows_stream(query: google.cloud.bigtable.data.read_rows_query.ReadRowsQuery, *, operation_timeout: float | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.READ_ROWS, attempt_timeout: float | None | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.READ_ROWS, retryable_errors: Union[Sequence[type[Exception]], google.cloud.bigtable.data._helpers.TABLE_DEFAULT] = TABLE_DEFAULT.READ_ROWS)
Read a set of rows from the table, based on the specified query. Returns an iterator to asynchronously stream back row data.
Failed requests within operation_timeout will be retried based on the retryable_errors list until operation_timeout is reached.
Parameters
query – contains details about which rows to return
operation_timeout – the time budget for the entire operation, in seconds. Failed requests will be retried within the budget. Defaults to the Table’s default_read_rows_operation_timeout
attempt_timeout – the time budget for an individual network request, in seconds. If it takes longer than this time to complete, the request will be cancelled with a DeadlineExceeded exception, and a retry will be attempted. Defaults to the Table’s default_read_rows_attempt_timeout. If None, defaults to operation_timeout.
retryable_errors – a list of errors that will be retried if encountered. Defaults to the Table’s default_read_rows_retryable_errors
Returns
an asynchronous iterator that yields rows returned by the query
Return type
AsyncIterable[Row]
Raises
google.api_core.exceptions.DeadlineExceeded – raised after operation timeout will be chained with a RetryExceptionGroup containing GoogleAPIError exceptions from any retries that failed
google.api_core.exceptions.GoogleAPIError – raised if the request encounters an unrecoverable error
async row_exists(row_key: str | bytes, *, operation_timeout: float | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.READ_ROWS, attempt_timeout: float | None | google.cloud.bigtable.data._helpers.TABLE_DEFAULT = TABLE_DEFAULT.READ_ROWS, retryable_errors: Union[Sequence[type[Exception]], google.cloud.bigtable.data._helpers.TABLE_DEFAULT] = TABLE_DEFAULT.READ_ROWS)
Return a boolean indicating whether the specified row exists in the table. uses the filters: chain(limit cells per row = 1, strip value)
Parameters
row_key – the key of the row to check
operation_timeout – the time budget for the entire operation, in seconds. Failed requests will be retried within the budget. Defaults to the Table’s default_read_rows_operation_timeout
attempt_timeout – the time budget for an individual network request, in seconds. If it takes longer than this time to complete, the request will be cancelled with a DeadlineExceeded exception, and a retry will be attempted. Defaults to the Table’s default_read_rows_attempt_timeout. If None, defaults to operation_timeout.
retryable_errors – a list of errors that will be retried if encountered. Defaults to the Table’s default_read_rows_retryable_errors.
Returns
a bool indicating whether the row exists
Return type
Raises
google.api_core.exceptions.DeadlineExceeded – raised after operation timeout will be chained with a RetryExceptionGroup containing GoogleAPIError exceptions from any retries that failed
google.api_core.exceptions.GoogleAPIError – raised if the request encounters an unrecoverable error
async sample_row_keys(*, operation_timeout: float | TABLE_DEFAULT = TABLE_DEFAULT.DEFAULT, attempt_timeout: float | None | TABLE_DEFAULT = TABLE_DEFAULT.DEFAULT, retryable_errors: Sequence[type[Exception]] | TABLE_DEFAULT = TABLE_DEFAULT.DEFAULT)
Return a set of RowKeySamples that delimit contiguous sections of the table of approximately equal size
RowKeySamples output can be used with ReadRowsQuery.shard() to create a sharded query that can be parallelized across multiple backend nodes read_rows and read_rows_stream requests will call sample_row_keys internally for this purpose when sharding is enabled
RowKeySamples is simply a type alias for list[tuple[bytes, int]]; a list of row_keys, along with offset positions in the table
Parameters
operation_timeout – the time budget for the entire operation, in seconds. Failed requests will be retried within the budget.i Defaults to the Table’s default_operation_timeout
attempt_timeout – the time budget for an individual network request, in seconds. If it takes longer than this time to complete, the request will be cancelled with a DeadlineExceeded exception, and a retry will be attempted. Defaults to the Table’s default_attempt_timeout. If None, defaults to operation_timeout.
retryable_errors – a list of errors that will be retried if encountered. Defaults to the Table’s default_retryable_errors.
Returns
a set of RowKeySamples the delimit contiguous sections of the table
Return type
RowKeySamples
Raises
google.api_core.exceptions.DeadlineExceeded – raised after operation timeout will be chained with a RetryExceptionGroup containing GoogleAPIError exceptions from any retries that failed
google.api_core.exceptions.GoogleAPIError – raised if the request encounters an unrecoverable error