diff --git a/README.rst b/README.rst index 5f7d5809d..2bc151e95 100644 --- a/README.rst +++ b/README.rst @@ -20,6 +20,24 @@ Analytics, Maps, and Gmail. .. _Client Library Documentation: https://googleapis.dev/python/bigtable/latest .. _Product Documentation: https://cloud.google.com/bigtable/docs + +Preview Async Data Client +------------------------- + +:code:`v2.23.0` includes a preview release of the new :code:`BigtableDataClientAsync` client, accessible at the import path +:code:`google.cloud.bigtable.data`. + +The new client brings a simplified API and increased performance using asyncio, with a corresponding synchronous surface +coming soon. The new client is focused on the data API (i.e. reading and writing Bigtable data), with admin operations +remaining in the existing client. + +:code:`BigtableDataClientAsync` is currently in preview, and is not recommended for production use. + +Feedback and bug reports are welcome at cbt-python-client-v3-feedback@google.com, +or through the Github `issue tracker`_. + +.. _issue tracker: https://github.com/googleapis/python-bigtable/issues + Quick Start ----------- @@ -94,14 +112,3 @@ Next Steps to see other available methods on the client. - Read the `Product documentation`_ to learn more about the product and see How-to Guides. - -``google-cloud-happybase`` --------------------------- - -In addition to the core ``google-cloud-bigtable``, we provide a -`google-cloud-happybase -`__ library -with the same interface as the popular `HappyBase -`__ library. Unlike HappyBase, -``google-cloud-happybase`` uses ``google-cloud-bigtable`` under the covers, -rather than Apache HBase. diff --git a/google/cloud/bigtable/data/README.rst b/google/cloud/bigtable/data/README.rst new file mode 100644 index 000000000..7a05cf913 --- /dev/null +++ b/google/cloud/bigtable/data/README.rst @@ -0,0 +1,11 @@ +Async Data Client Preview +========================= + +This new client is currently in preview, and is not recommended for production use. + +Synchronous API surface and usage examples coming soon + +Feedback and bug reports are welcome at cbt-python-client-v3-feedback@google.com, +or through the Github `issue tracker`_. + +.. _issue tracker: https://github.com/googleapis/python-bigtable/issues diff --git a/google/cloud/bigtable/data/_async/client.py b/google/cloud/bigtable/data/_async/client.py index da54b37cb..ed14c618d 100644 --- a/google/cloud/bigtable/data/_async/client.py +++ b/google/cloud/bigtable/data/_async/client.py @@ -101,6 +101,9 @@ def __init__( Client should be created within an async context (running event loop) + Warning: BigtableDataClientAsync is currently in preview, and is not + yet recommended for production use. + Args: project: the project which the client acts on behalf of. If not passed, falls back to the default inferred @@ -563,6 +566,9 @@ async def read_rows_stream( Failed requests within operation_timeout will be retried based on the retryable_errors list until operation_timeout is reached. + Warning: BigtableDataClientAsync is currently in preview, and is not + yet recommended for production use. + Args: - query: contains details about which rows to return - operation_timeout: the time budget for the entire operation, in seconds. @@ -614,6 +620,9 @@ async def read_rows( Failed requests within operation_timeout will be retried based on the retryable_errors list until operation_timeout is reached. + Warning: BigtableDataClientAsync is currently in preview, and is not + yet recommended for production use. + Args: - query: contains details about which rows to return - operation_timeout: the time budget for the entire operation, in seconds. @@ -660,6 +669,9 @@ async def read_row( Failed requests within operation_timeout will be retried based on the retryable_errors list until operation_timeout is reached. + Warning: BigtableDataClientAsync is currently in preview, and is not + yet recommended for production use. + Args: - query: contains details about which rows to return - operation_timeout: the time budget for the entire operation, in seconds. @@ -715,6 +727,9 @@ async def read_rows_sharded( results = await table.read_rows_sharded(shard_queries) ``` + Warning: BigtableDataClientAsync is currently in preview, and is not + yet recommended for production use. + Args: - sharded_query: a sharded query to execute - operation_timeout: the time budget for the entire operation, in seconds. @@ -795,6 +810,9 @@ async def row_exists( Return a boolean indicating whether the specified row exists in the table. uses the filters: chain(limit cells per row = 1, strip value) + Warning: BigtableDataClientAsync is currently in preview, and is not + yet recommended for production use. + Args: - row_key: the key of the row to check - operation_timeout: the time budget for the entire operation, in seconds. @@ -849,6 +867,9 @@ async def sample_row_keys( RowKeySamples is simply a type alias for list[tuple[bytes, int]]; a list of row_keys, along with offset positions in the table + Warning: BigtableDataClientAsync is currently in preview, and is not + yet recommended for production use. + Args: - operation_timeout: the time budget for the entire operation, in seconds. Failed requests will be retried within the budget.i @@ -921,6 +942,9 @@ def mutations_batcher( Can be used to iteratively add mutations that are flushed as a group, to avoid excess network calls + Warning: BigtableDataClientAsync is currently in preview, and is not + yet recommended for production use. + Args: - flush_interval: Automatically flush every flush_interval seconds. If None, a table default will be used @@ -962,35 +986,38 @@ async def mutate_row( | TABLE_DEFAULT = TABLE_DEFAULT.DEFAULT, ): """ - Mutates a row atomically. + Mutates a row atomically. - Cells already present in the row are left unchanged unless explicitly changed - by ``mutation``. + 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. + Idempotent operations (i.e, all mutations have an explicit timestamp) will be + retried on server failure. Non-idempotent operations will not. - Args: - - 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. + Warning: BigtableDataClientAsync is currently in preview, and is not + yet recommended for production use. + + Args: + - 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: - - DeadlineExceeded: raised after operation timeout - will be chained with a RetryExceptionGroup containing all - GoogleAPIError exceptions from any retries that failed - - GoogleAPIError: raised on non-idempotent operations that cannot be - safely retried. - - ValueError if invalid arguments are provided + - DeadlineExceeded: raised after operation timeout + will be chained with a RetryExceptionGroup containing all + GoogleAPIError exceptions from any retries that failed + - GoogleAPIError: raised on non-idempotent operations that cannot be + safely retried. + - ValueError if invalid arguments are provided """ operation_timeout, attempt_timeout = _get_timeouts( operation_timeout, attempt_timeout, self @@ -1050,6 +1077,9 @@ async def bulk_mutate_rows( will be retried on failure. Non-idempotent will not, and will reported in a raised exception group + Warning: BigtableDataClientAsync is currently in preview, and is not + yet recommended for production use. + Args: - mutation_entries: the batches of mutations to apply Each entry will be applied atomically, but entries will be applied @@ -1098,6 +1128,9 @@ async def check_and_mutate_row( Non-idempotent operation: will not be retried + Warning: BigtableDataClientAsync is currently in preview, and is not + yet recommended for production use. + Args: - row_key: the key of the row to mutate - predicate: the filter to be applied to the contents of the specified row. @@ -1166,6 +1199,9 @@ async def read_modify_write_row( Non-idempotent operation: will not be retried + Warning: BigtableDataClientAsync is currently in preview, and is not + yet recommended for production use. + Args: - 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.