diff --git a/docs/bigtable-client-intro.rst b/docs/bigtable-client-intro.rst index 6c7e48790f3d..3f43371ec1db 100644 --- a/docs/bigtable-client-intro.rst +++ b/docs/bigtable-client-intro.rst @@ -21,18 +21,19 @@ defaults However, you may over-ride them and these will be used throughout all API requests made with the ``client`` you create. -Authorization +Configuration ------------- - For an overview of authentication in ``gcloud-python``, see :doc:`gcloud-auth`. - In addition to any authentication configuration, you can also set the - :envvar:`GCLOUD_PROJECT` environment variable for the project you'd like - to interact with. If you are Google App Engine or Google Compute Engine - this will be detected automatically. (Setting this environment - variable is not required, you may instead pass the ``project`` explicitly - when constructing a :class:`Client `). + :envvar:`GCLOUD_PROJECT` environment variable for the Google Cloud Console + project you'd like to interact with. If your code is running in Google App + Engine or Google Compute Engine the project will be detected automatically. + (Setting this environment variable is not required, you may instead pass the + ``project`` explicitly when constructing a + :class:`Client `). - After configuring your environment, create a :class:`Client ` diff --git a/docs/bigtable-cluster-api.rst b/docs/bigtable-cluster-api.rst index bedf581fbf44..17fba96840db 100644 --- a/docs/bigtable-cluster-api.rst +++ b/docs/bigtable-cluster-api.rst @@ -85,11 +85,13 @@ Check on Current Operation .. note:: When modifying a cluster (via a `CreateCluster`_, `UpdateCluster`_ or - `UndeleteCluster`_ request), the Bigtable API will return a long-running - `Operation`_. This will be stored on the object after each of + `UndeleteCluster`_ request), the Bigtable API will return a + `long-running operation`_ and a corresponding + :class:`Operation ` object + will be returned by each of :meth:`create() `, :meth:`update() ` and - :meth:`undelete() ` are called. + :meth:`undelete() `. You can check if a long-running operation (for a :meth:`create() `, @@ -176,4 +178,4 @@ Head next to learn about the :doc:`bigtable-table-api`. .. _ListClusters: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/bigtable/admin/cluster/v1/bigtable_cluster_service.proto#L44-L46 .. _GetOperation: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/longrunning/operations.proto#L43-L45 .. _UndeleteCluster: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/bigtable/admin/cluster/v1/bigtable_cluster_service.proto#L126-L128 -.. _Operation: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/longrunning/operations.proto#L73-L102 +.. _long-running operation: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/longrunning/operations.proto#L73-L102 diff --git a/docs/bigtable-data-api.rst b/docs/bigtable-data-api.rst index 776fe4a8429f..779efa991886 100644 --- a/docs/bigtable-data-api.rst +++ b/docs/bigtable-data-api.rst @@ -24,23 +24,11 @@ Cells vs. Columns vs. Column Families Modifying Data ++++++++++++++ -Since data is stored in cells, which are stored in rows, the -:class:`Row ` class is the only class used to -modify (write, update, delete) data in a +Since data is stored in cells, which are stored in rows, we +use the metaphor of a **row** in classes that are used to modify +(write, update, delete) data in a :class:`Table `. -Row Factory ------------ - -To create a :class:`Row ` object - -.. code:: python - - row = table.row(row_key) - -Unlike the previous string values we've used before, the row key must -be ``bytes``. - Direct vs. Conditional vs. Append --------------------------------- @@ -49,43 +37,65 @@ There are three ways to modify data in a table, described by the methods. * The **direct** way is via `MutateRow`_ which involves simply - adding, overwriting or deleting cells. + adding, overwriting or deleting cells. The + :class:`DirectRow ` class + handles direct mutations. * The **conditional** way is via `CheckAndMutateRow`_. This method first checks if some filter is matched in a a given row, then applies one of two sets of mutations, depending on if a match occurred or not. (These mutation sets are called the "true - mutations" and "false mutations".) + mutations" and "false mutations".) The + :class:`ConditionalRow ` class + handles conditional mutations. * The **append** way is via `ReadModifyWriteRow`_. This simply appends (as bytes) or increments (as an integer) data in a presumed - existing cell in a row. + existing cell in a row. The + :class:`AppendRow ` class + handles append mutations. -Building Up Mutations ---------------------- +Row Factory +----------- -In all three cases, a set of mutations (or two sets) are built up -on a :class:`Row ` before they are sent of -in a batch via :meth:`commit() `: +A single factory can be used to create any of the three row types. +To create a :class:`DirectRow `: .. code:: python - row.commit() + row = table.row(row_key) -To send **append** mutations in batch, use -:meth:`commit_modifications() `: +Unlike the previous string values we've used before, the row key must +be ``bytes``. + +To create a :class:`ConditionalRow `, +first create a :class:`RowFilter ` and +then .. code:: python - row.commit_modifications() + cond_row = table.row(row_key, filter_=filter_) -We have a small set of methods on the :class:`Row ` -to build these mutations up. +To create an :class:`AppendRow ` + +.. code:: python + + append_row = table.row(row_key, append=True) + +Building Up Mutations +--------------------- + +In all three cases, a set of mutations (or two sets) are built up +on a row before they are sent of in a batch via + +.. code:: python + + row.commit() Direct Mutations ---------------- Direct mutations can be added via one of four methods -* :meth:`set_cell() ` allows a +* :meth:`set_cell() ` allows a single value to be written to a column .. code:: python @@ -97,9 +107,9 @@ Direct mutations can be added via one of four methods Bigtable server will be used when the cell is stored. The value can either by bytes or an integer (which will be converted to - bytes as an unsigned 64-bit integer). + bytes as a signed 64-bit integer). -* :meth:`delete_cell() ` deletes +* :meth:`delete_cell() ` deletes all cells (i.e. for all timestamps) in a given column .. code:: python @@ -117,8 +127,9 @@ Direct mutations can be added via one of four methods row.delete_cell(column_family_id, column, time_range=time_range) -* :meth:`delete_cells() ` does - the same thing as :meth:`delete_cell() ` +* :meth:`delete_cells() ` does + the same thing as + :meth:`delete_cell() ` but accepts a list of columns in a column family rather than a single one. .. code:: python @@ -127,15 +138,16 @@ Direct mutations can be added via one of four methods time_range=time_range) In addition, if we want to delete cells from every column in a column family, - the special :attr:`ALL_COLUMNS ` value - can be used + the special :attr:`ALL_COLUMNS ` + value can be used .. code:: python - row.delete_cells(column_family_id, Row.ALL_COLUMNS, + row.delete_cells(column_family_id, row.ALL_COLUMNS, time_range=time_range) -* :meth:`delete() ` will delete the entire row +* :meth:`delete() ` will delete the + entire row .. code:: python @@ -145,57 +157,42 @@ Conditional Mutations --------------------- Making **conditional** modifications is essentially identical -to **direct** modifications, but we need to specify a filter to match -against in the row: +to **direct** modifications: it uses the exact same methods +to accumulate mutations. -.. code:: python - - row = table.row(row_key, filter_=filter_val) - -See the :class:`Row ` class for more information -about acceptable values for ``filter_``. - -The only other difference from **direct** modifications are that each mutation -added must specify a ``state``: will the mutation be applied if the filter -matches or if it fails to match. +However, each mutation added must specify a ``state``: will the mutation be +applied if the filter matches or if it fails to match. For example: .. code:: python - row.set_cell(column_family_id, column, value, - timestamp=timestamp, state=True) + cond_row.set_cell(column_family_id, column, value, + timestamp=timestamp, state=True) will add to the set of true mutations. -.. note:: - - If ``state`` is passed when no ``filter_`` is set on a - :class:`Row `, adding the mutation will fail. - Similarly, if no ``state`` is passed when a ``filter_`` has been set, - adding the mutation will fail. - Append Mutations ---------------- Append mutations can be added via one of two methods -* :meth:`append_cell_value() ` +* :meth:`append_cell_value() ` appends a bytes value to an existing cell: .. code:: python - row.append_cell_value(column_family_id, column, bytes_value) + append_row.append_cell_value(column_family_id, column, bytes_value) -* :meth:`increment_cell_value() ` +* :meth:`increment_cell_value() ` increments an integer value in an existing cell: .. code:: python - row.increment_cell_value(column_family_id, column, int_value) + append_row.increment_cell_value(column_family_id, column, int_value) Since only bytes are stored in a cell, the cell value is decoded as - an unsigned 64-bit integer before being incremented. (This happens on + a signed 64-bit integer before being incremented. (This happens on the Google Cloud Bigtable server, not in the library.) Notice that no timestamp was specified. This is because **append** mutations @@ -208,18 +205,10 @@ Starting Fresh -------------- If accumulated mutations need to be dropped, use -:meth:`clear_mutations() ` - -.. code:: python - - row.clear_mutations() - -To clear **append** mutations, use -:meth:`clear_modification_rules() ` .. code:: python - row.clear_modification_rules() + row.clear() Reading Data ++++++++++++ @@ -260,19 +249,20 @@ To make a `ReadRows`_ API request for a single row key, use >>> cell.timestamp datetime.datetime(2016, 2, 27, 3, 41, 18, 122823, tzinfo=) -Rather than returning a :class:`Row `, this method -returns a :class:`PartialRowData ` +Rather than returning a :class:`DirectRow ` +or similar class, this method returns a +:class:`PartialRowData ` instance. This class is used for reading and parsing data rather than for -modifying data (as :class:`Row ` is). +modifying data (as :class:`DirectRow ` is). -A filter can also be applied to the +A filter can also be applied to the results: .. code:: python row_data = table.read_row(row_key, filter_=filter_val) The allowable ``filter_`` values are the same as those used for a -:class:`Row ` with **conditional** mutations. For +:class:`ConditionalRow `. For more information, see the :meth:`Table.read_row() ` documentation. diff --git a/docs/bigtable-row.rst b/docs/bigtable-row.rst index 08ae1d4beaae..fae56b76f3d5 100644 --- a/docs/bigtable-row.rst +++ b/docs/bigtable-row.rst @@ -2,7 +2,8 @@ Bigtable Row ============ It is possible to use a :class:`RowFilter ` -when adding mutations to a :class:`Row ` and when +when adding mutations to a +:class:`ConditionalRow ` and when reading row data with :meth:`read_row() ` :meth:`read_rows() `. diff --git a/gcloud/bigtable/row.py b/gcloud/bigtable/row.py index 2e322e2e05d0..276f009b7bb1 100644 --- a/gcloud/bigtable/row.py +++ b/gcloud/bigtable/row.py @@ -73,10 +73,10 @@ class DirectRow(Row): .. note:: - A :class:`Row` accumulates mutations locally via the :meth:`set_cell`, - :meth:`delete`, :meth:`delete_cell` and :meth:`delete_cells` methods. - To actually send these mutations to the Google Cloud Bigtable API, you - must call :meth:`commit`. + A :class:`DirectRow` accumulates mutations locally via the + :meth:`set_cell`, :meth:`delete`, :meth:`delete_cell` and + :meth:`delete_cells` methods. To actually send these mutations to the + Google Cloud Bigtable API, you must call :meth:`commit`. :type row_key: bytes :param row_key: The key for the current row. @@ -585,8 +585,10 @@ def delete_cells(self, column_family_id, columns, time_range=None, :type columns: :class:`list` of :class:`str` / :func:`unicode `, or :class:`object` :param columns: The columns within the column family that will have - cells deleted. If :attr:`ALL_COLUMNS` is used then - the entire column family will be deleted from the row. + cells deleted. If + :attr:`ALL_COLUMNS <.DirectRow.ALL_COLUMNS>` is used + then the entire column family will be deleted from + the row. :type time_range: :class:`TimestampRange` :param time_range: (Optional) The range of time within which cells @@ -641,7 +643,7 @@ def append_cell_value(self, column_family_id, column, value): .. note:: This method adds a read-modify rule protobuf to the accumulated - read-modify rules on this :class:`Row`, but does not make an API + read-modify rules on this row, but does not make an API request. To actually send an API request (with the rules) to the Google Cloud Bigtable API, call :meth:`commit`. @@ -675,7 +677,7 @@ def increment_cell_value(self, column_family_id, column, int_value): .. note:: This method adds a read-modify rule protobuf to the accumulated - read-modify rules on this :class:`Row`, but does not make an API + read-modify rules on this row, but does not make an API request. To actually send an API request (with the rules) to the Google Cloud Bigtable API, call :meth:`commit`. @@ -715,6 +717,8 @@ def commit(self): server time or the highest timestamp of a cell in that column (if it exceeds the server time). + After committing the accumulated mutations, resets the local mutations. + .. code:: python >>> append_row.commit()