Version History (0.17.0)
Report an Issue

Bigtable Row#

Warning

gRPC is required for using the Cloud Bigtable API. As of May 2016, grpcio is only supported in Python 2.7, so importing gcloud.bigtable in other versions of Python will fail.

User friendly container for Google Cloud Bigtable Row.

class gcloud.bigtable.row.AppendRow(row_key, table)[source]#

Bases: gcloud.bigtable.row.Row

Google Cloud Bigtable Row for sending append mutations.

These mutations are intended to augment the value of an existing cell and uses the methods:

The first works by appending bytes and the second by incrementing an integer (stored in the cell as 8 bytes). In either case, if the cell is empty, assumes the default empty value (empty string for bytes or and 0 for integer).

Parameters:
  • row_key (bytes) – The key for the current row.
  • table (Table) – The table that owns the row.
append_cell_value(column_family_id, column, value)[source]#

Appends a value to an existing cell.

Note

This method adds a read-modify rule protobuf to the accumulated 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 commit().

Parameters:
  • column_family_id (str) – The column family that contains the column. Must be of the form [_a-zA-Z0-9][-_.a-zA-Z0-9]*.
  • column (bytes) – The column within the column family where the cell is located.
  • value (bytes) – The value to append to the existing value in the cell. If the targeted cell is unset, it will be treated as containing the empty string.
clear()[source]#

Removes all currently accumulated modifications on current row.

commit()[source]#

Makes a ReadModifyWriteRow API request.

This commits modifications made by append_cell_value() and increment_cell_value(). If no modifications were made, makes no API request and just returns {}.

Modifies a row atomically, reading the latest existing timestamp / value from the specified columns and writing a new value by appending / incrementing. The new cell created uses either the current 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.

>>> append_row.commit()
{
    u'col-fam-id': {
        b'col-name1': [
            (b'cell-val', datetime.datetime(...)),
            (b'cell-val-newer', datetime.datetime(...)),
        ],
        b'col-name2': [
            (b'altcol-cell-val', datetime.datetime(...)),
        ],
    },
    u'col-fam-id2': {
        b'col-name3-but-other-fam': [
            (b'foo', datetime.datetime(...)),
        ],
    },
}
Return type:dict
Returns:The new contents of all modified cells. Returned as a dictionary of column families, each of which holds a dictionary of columns. Each column contains a list of cells modified. Each cell is represented with a two-tuple with the value (in bytes) and the timestamp for the cell.
Raises:ValueError if the number of mutations exceeds the MAX_MUTATIONS.
increment_cell_value(column_family_id, column, int_value)[source]#

Increments a value in an existing cell.

Assumes the value in the cell is stored as a 64 bit integer serialized to bytes.

Note

This method adds a read-modify rule protobuf to the accumulated 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 commit().

Parameters:
  • column_family_id (str) – The column family that contains the column. Must be of the form [_a-zA-Z0-9][-_.a-zA-Z0-9]*.
  • column (bytes) – The column within the column family where the cell is located.
  • int_value (int) – The value to increment the existing value in the cell by. If the targeted cell is unset, it will be treated as containing a zero. Otherwise, the targeted cell must contain an 8-byte value (interpreted as a 64-bit big-endian signed integer), or the entire request will fail.
class gcloud.bigtable.row.ConditionalRow(row_key, table, filter_)[source]#

Bases: gcloud.bigtable.row._SetDeleteRow

Google Cloud Bigtable Row for sending mutations conditionally.

Each mutation has an associated state: True or False. When commit()-ed, the mutations for the True state will be applied if the filter matches any cells in the row, otherwise the False state will be applied.

A ConditionalRow accumulates mutations in the same way a DirectRow does:

with the only change the extra state parameter:

>>> row_cond = table.row(b'row-key2', filter_=row_filter)
>>> row_cond.set_cell(u'fam', b'col', b'cell-val', state=True)
>>> row_cond.delete_cell(u'fam', b'col', state=False)

Note

As with DirectRow, to actually send these mutations to the Google Cloud Bigtable API, you must call commit().

Parameters:
  • row_key (bytes) – The key for the current row.
  • table (Table) – The table that owns the row.
  • filter (RowFilter) – Filter to be used for conditional mutations.
clear()[source]#

Removes all currently accumulated mutations on the current row.

commit()[source]#

Makes a CheckAndMutateRow API request.

If no mutations have been created in the row, no request is made.

The mutations will be applied conditionally, based on whether the filter matches any cells in the ConditionalRow or not. (Each method which adds a mutation has a state parameter for this purpose.)

Mutations are applied atomically and in order, meaning that earlier mutations can be masked / negated by later ones. Cells already present in the row are left unchanged unless explicitly changed by a mutation.

After committing the accumulated mutations, resets the local mutations.

Return type:bool
Returns:Flag indicating if the filter was matched (which also indicates which set of mutations were applied by the server).
Raises:ValueError if the number of mutations exceeds the MAX_MUTATIONS.
delete(state=True)[source]#

Deletes this row from the table.

Note

This method adds a mutation to the accumulated mutations on this row, but does not make an API request. To actually send an API request (with the mutations) to the Google Cloud Bigtable API, call commit().

Parameters:state (bool) – (Optional) The state that the mutation should be applied in. Defaults to True.
delete_cell(column_family_id, column, time_range=None, state=True)[source]#

Deletes cell in this row.

Note

This method adds a mutation to the accumulated mutations on this row, but does not make an API request. To actually send an API request (with the mutations) to the Google Cloud Bigtable API, call commit().

Parameters:
  • column_family_id (str) – The column family that contains the column or columns with cells being deleted. Must be of the form [_a-zA-Z0-9][-_.a-zA-Z0-9]*.
  • column (bytes) – The column within the column family that will have a cell deleted.
  • time_range (TimestampRange) – (Optional) The range of time within which cells should be deleted.
  • state (bool) – (Optional) The state that the mutation should be applied in. Defaults to True.
delete_cells(column_family_id, columns, time_range=None, state=True)[source]#

Deletes cells in this row.

Note

This method adds a mutation to the accumulated mutations on this row, but does not make an API request. To actually send an API request (with the mutations) to the Google Cloud Bigtable API, call commit().

Parameters:
  • column_family_id (str) – The column family that contains the column or columns with cells being deleted. Must be of the form [_a-zA-Z0-9][-_.a-zA-Z0-9]*.
  • columns (list of str / unicode, or object) – The columns within the column family that will have cells deleted. If ALL_COLUMNS is used then the entire column family will be deleted from the row.
  • time_range (TimestampRange) – (Optional) The range of time within which cells should be deleted.
  • state (bool) – (Optional) The state that the mutation should be applied in. Defaults to True.
set_cell(column_family_id, column, value, timestamp=None, state=True)[source]#

Sets a value in this row.

The cell is determined by the row_key of this ConditionalRow and the column. The column must be in an existing ColumnFamily (as determined by column_family_id).

Note

This method adds a mutation to the accumulated mutations on this row, but does not make an API request. To actually send an API request (with the mutations) to the Google Cloud Bigtable API, call commit().

Parameters:
  • column_family_id (str) – The column family that contains the column. Must be of the form [_a-zA-Z0-9][-_.a-zA-Z0-9]*.
  • column (bytes) – The column within the column family where the cell is located.
  • value (bytes or int) – The value to set in the cell. If an integer is used, will be interpreted as a 64-bit big-endian signed integer (8 bytes).
  • timestamp (datetime.datetime) – (Optional) The timestamp of the operation.
  • state (bool) – (Optional) The state that the mutation should be applied in. Defaults to True.
class gcloud.bigtable.row.DirectRow(row_key, table)[source]#

Bases: gcloud.bigtable.row._SetDeleteRow

Google Cloud Bigtable Row for sending “direct” mutations.

These mutations directly set or delete cell contents:

These methods can be used directly:

>>> row = table.row(b'row-key1')
>>> row.set_cell(u'fam', b'col1', b'cell-val')
>>> row.delete_cell(u'fam', b'col2')

Note

A DirectRow accumulates mutations locally via the set_cell(), delete(), delete_cell() and delete_cells() methods. To actually send these mutations to the Google Cloud Bigtable API, you must call commit().

Parameters:
  • row_key (bytes) – The key for the current row.
  • table (Table) – The table that owns the row.
clear()[source]#

Removes all currently accumulated mutations on the current row.

commit()[source]#

Makes a MutateRow API request.

If no mutations have been created in the row, no request is made.

Mutations are applied atomically and in order, meaning that earlier mutations can be masked / negated by later ones. Cells already present in the row are left unchanged unless explicitly changed by a mutation.

After committing the accumulated mutations, resets the local mutations to an empty list.

Raises:ValueError if the number of mutations exceeds the MAX_MUTATIONS.
delete()[source]#

Deletes this row from the table.

Note

This method adds a mutation to the accumulated mutations on this row, but does not make an API request. To actually send an API request (with the mutations) to the Google Cloud Bigtable API, call commit().

delete_cell(column_family_id, column, time_range=None)[source]#

Deletes cell in this row.

Note

This method adds a mutation to the accumulated mutations on this row, but does not make an API request. To actually send an API request (with the mutations) to the Google Cloud Bigtable API, call commit().

Parameters:
  • column_family_id (str) – The column family that contains the column or columns with cells being deleted. Must be of the form [_a-zA-Z0-9][-_.a-zA-Z0-9]*.
  • column (bytes) – The column within the column family that will have a cell deleted.
  • time_range (TimestampRange) – (Optional) The range of time within which cells should be deleted.
delete_cells(column_family_id, columns, time_range=None)[source]#

Deletes cells in this row.

Note

This method adds a mutation to the accumulated mutations on this row, but does not make an API request. To actually send an API request (with the mutations) to the Google Cloud Bigtable API, call commit().

Parameters:
  • column_family_id (str) – The column family that contains the column or columns with cells being deleted. Must be of the form [_a-zA-Z0-9][-_.a-zA-Z0-9]*.
  • columns (list of str / unicode, or object) – The columns within the column family that will have cells deleted. If ALL_COLUMNS is used then the entire column family will be deleted from the row.
  • time_range (TimestampRange) – (Optional) The range of time within which cells should be deleted.
set_cell(column_family_id, column, value, timestamp=None)[source]#

Sets a value in this row.

The cell is determined by the row_key of this DirectRow and the column. The column must be in an existing ColumnFamily (as determined by column_family_id).

Note

This method adds a mutation to the accumulated mutations on this row, but does not make an API request. To actually send an API request (with the mutations) to the Google Cloud Bigtable API, call commit().

Parameters:
  • column_family_id (str) – The column family that contains the column. Must be of the form [_a-zA-Z0-9][-_.a-zA-Z0-9]*.
  • column (bytes) – The column within the column family where the cell is located.
  • value (bytes or int) – The value to set in the cell. If an integer is used, will be interpreted as a 64-bit big-endian signed integer (8 bytes).
  • timestamp (datetime.datetime) – (Optional) The timestamp of the operation.
gcloud.bigtable.row.MAX_MUTATIONS = 100000#

The maximum number of mutations that a row can accumulate.

class gcloud.bigtable.row.Row(row_key, table)[source]#

Bases: object

Base representation of a Google Cloud Bigtable Row.

This class has three subclasses corresponding to the three RPC methods for sending row mutations:

Parameters:
  • row_key (bytes) – The key for the current row.
  • table (Table) – The table that owns the row.