As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

Bigtable Row

User-friendly container for Google Cloud Bigtable Row.

class google.cloud.bigtable.row.AppendRow(row_key, table)[source]

Bases: google.cloud.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 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().

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)
row = table.row(ROW_KEY1, append=True)

cell_val2 = b"2"
row.append_cell_value(COLUMN_FAMILY_ID, COL_NAME1, cell_val2)
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.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row_key = b"row_key_1"
row_obj = table.row(row_key)
row_obj.set_cell(COLUMN_FAMILY_ID, COL_NAME1, b"cell-val")

row_obj.clear()
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.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row_key = b"row_key_2"
cell_val = b"cell-val"
row_obj = table.row(row_key)
row_obj.set_cell(COLUMN_FAMILY_ID, COL_NAME1, cell_val)
row_obj.commit()
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().

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)
row = table.row(ROW_KEY2, append=True)

int_val = 3
row.increment_cell_value(COLUMN_FAMILY_ID, COL_NAME1, int_val)
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.

property row_key

Row key.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row = table.row(ROW_KEY1)
row_key = row.row_key
Return type

bytes

Returns

The key for the current row.

property table

Row table.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row = table.row(ROW_KEY1)
table1 = row.table
Return type

table: Table

Returns

table: The table that owns the row.

class google.cloud.bigtable.row.Cell(value, timestamp_micros, labels=None)[source]

Bases: object

Representation of a Google Cloud Bigtable Cell.

Parameters

  • value (bytes) – The value stored in the cell.

  • timestamp_micros (int) – The timestamp_micros when the cell was stored.

  • labels (list) – (Optional) List of strings. Labels applied to the cell.

classmethod from_pb(cell_pb)[source]

Create a new cell from a Cell protobuf.

Parameters

cell_pb (_generated.data_pb2.Cell) – The protobuf to convert.

Return type

Cell

Returns

The cell corresponding to the protobuf.

class google.cloud.bigtable.row.ConditionalRow(row_key, table, filter_)[source]

Bases: google.cloud.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.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row_key = b"row_key_1"
row_obj = table.row(row_key)
row_obj.set_cell(COLUMN_FAMILY_ID, COL_NAME1, b"cell-val")

row_obj.clear()
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.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row_key = b"row_key_2"
cell_val = b"cell-val"
row_obj = table.row(row_key)
row_obj.set_cell(COLUMN_FAMILY_ID, COL_NAME1, cell_val)
row_obj.commit()
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().

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row_key = b"row_key_1"
row_obj = table.row(row_key)

row_obj.delete()
row_obj.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().

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row_key = b"row_key_1"
row_obj = table.row(row_key)

row_obj.delete_cell(COLUMN_FAMILY_ID, COL_NAME1)
row_obj.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().

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row_key = b"row_key_1"
row_obj = table.row(row_key)

row_obj.delete_cells(COLUMN_FAMILY_ID, [COL_NAME1, COL_NAME2])
row_obj.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.

property row_key

Row key.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row = table.row(ROW_KEY1)
row_key = row.row_key
Return type

bytes

Returns

The key for the current row.

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().

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)
row = table.row(ROW_KEY1)

cell_val = b"cell-val"
row.set_cell(
    COLUMN_FAMILY_ID, COL_NAME1, cell_val, timestamp=datetime.datetime.utcnow()
)
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.

property table

Row table.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row = table.row(ROW_KEY1)
table1 = row.table
Return type

table: Table

Returns

table: The table that owns the row.

class google.cloud.bigtable.row.DirectRow(row_key, table=None)[source]

Bases: google.cloud.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) – (Optional) The table that owns the row. This is used for the :meth: commit only. Alternatively, DirectRows can be persisted via mutate_rows().

clear()[source]

Removes all currently accumulated mutations on the current row.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row_key = b"row_key_1"
row_obj = table.row(row_key)
row_obj.set_cell(COLUMN_FAMILY_ID, COL_NAME1, b"cell-val")

row_obj.clear()
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.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row_key = b"row_key_2"
cell_val = b"cell-val"
row_obj = table.row(row_key)
row_obj.set_cell(COLUMN_FAMILY_ID, COL_NAME1, cell_val)
row_obj.commit()
Return type

Status

Returns

A response status (google.rpc.status_pb2.Status) representing success or failure of the row committed.

Raises

TooManyMutationsError if the number of mutations is greater than 100,000.

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().

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row_key = b"row_key_1"
row_obj = table.row(row_key)

row_obj.delete()
row_obj.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().

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row_key = b"row_key_1"
row_obj = table.row(row_key)

row_obj.delete_cell(COLUMN_FAMILY_ID, COL_NAME1)
row_obj.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().

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row_key = b"row_key_1"
row_obj = table.row(row_key)

row_obj.delete_cells(COLUMN_FAMILY_ID, [COL_NAME1, COL_NAME2])
row_obj.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.

get_mutations_size()[source]

Gets the total mutations size for current row

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row_key_id = b"row_key_1"
row_obj = table.row(row_key_id)

mutation_size = row_obj.get_mutations_size()
property row_key

Row key.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row = table.row(ROW_KEY1)
row_key = row.row_key
Return type

bytes

Returns

The key for the current row.

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().

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)
row = table.row(ROW_KEY1)

cell_val = b"cell-val"
row.set_cell(
    COLUMN_FAMILY_ID, COL_NAME1, cell_val, timestamp=datetime.datetime.utcnow()
)
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.

property table

Row table.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row = table.row(ROW_KEY1)
table1 = row.table
Return type

table: Table

Returns

table: The table that owns the row.

exception google.cloud.bigtable.row.InvalidChunk[source]

Bases: RuntimeError

Exception raised to invalid chunk data from back-end.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

google.cloud.bigtable.row.MAX_MUTATIONS = 100000

The maximum number of mutations that a row can accumulate.

class google.cloud.bigtable.row.PartialRowData(row_key)[source]

Bases: object

Representation of partial row in a Google Cloud Bigtable Table.

These are expected to be updated directly from a _generated.bigtable_service_messages_pb2.ReadRowsResponse

Parameters

row_key (bytes) – The key for the row holding the (partial) data.

cell_value(column_family_id, column, index=0)[source]

Get a single cell value stored on this instance.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)
row_key = "row_key_1"
row_data = table.read_row(row_key)

cell_value = row_data.cell_value(COLUMN_FAMILY_ID, COL_NAME1)
Parameters

  • column_family_id (str) – The ID of the column family. 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.

  • index (Optional[int]) – The offset within the series of values. If not specified, will return the first cell.

Returns

The cell value stored in the specified column and specified index.

Return type

Cell value

Raises

  • KeyError – If column_family_id is not among the cells stored in this row.

  • KeyError – If column is not among the cells stored in this row for the given column_family_id.

  • IndexError – If index cannot be found within the cells stored in this row for the given column_family_id, column pair.

cell_values(column_family_id, column, max_count=None)[source]

Get a time series of cells stored on this instance.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)
row_key = "row_key_1"
row_data = table.read_row(row_key)

cell_values = row_data.cell_values(COLUMN_FAMILY_ID, COL_NAME1)
Parameters

  • column_family_id (str) – The ID of the column family. Must be of the form [_a-zA-Z0-9][-_.a-zA-Z0-9]*.

  • column (bytes) – The column within the column family where the cells are located.

  • max_count (int) – The maximum number of cells to use.

Returns

cell.value, cell.timestamp_micros

for each cell in the list of cells

Return type

A generator which provides

Raises

  • KeyError – If column_family_id is not among the cells stored in this row.

  • KeyError – If column is not among the cells stored in this row for the given column_family_id.

property cells

Property returning all the cells accumulated on this partial row.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)
row_key = "row_key_1"
row_data = table.read_row(row_key)

cells = row_data.cells
Return type

dict

Returns

Dictionary of the Cell objects accumulated. This dictionary has two-levels of keys (first for column families and second for column names/qualifiers within a family). For a given column, a list of Cell objects is stored.

find_cells(column_family_id, column)[source]

Get a time series of cells stored on this instance.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)
row_key = "row_key_1"
row = table.read_row(row_key)

cells = row.find_cells(COLUMN_FAMILY_ID, COL_NAME2)
Parameters

  • column_family_id (str) – The ID of the column family. Must be of the form [_a-zA-Z0-9][-_.a-zA-Z0-9]*.

  • column (bytes) – The column within the column family where the cells are located.

Returns

The cells stored in the specified column.

Return type

List[Cell]

Raises

  • KeyError – If column_family_id is not among the cells stored in this row.

  • KeyError – If column is not among the cells stored in this row for the given column_family_id.

property row_key

Getter for the current (partial) row’s key.

Return type

bytes

Returns

The current (partial) row’s key.

to_dict()[source]

Convert the cells to a dictionary.

This is intended to be used with HappyBase, so the column family and column qualiers are combined (with :).

Return type

dict

Returns

Dictionary containing all the data in the cells of this row.

class google.cloud.bigtable.row.Row(row_key, table=None)[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) – (Optional) The table that owns the row.

property row_key

Row key.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row = table.row(ROW_KEY1)
row_key = row.row_key
Return type

bytes

Returns

The key for the current row.

property table

Row table.

For example:

from google.cloud.bigtable import Client

client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table(TABLE_ID)

row = table.row(ROW_KEY1)
table1 = row.table
Return type

table: Table

Returns

table: The table that owns the row.