Row

User friendly container for Google Cloud Bigtable Row.

class gcloud_bigtable.row.CellValueRange(start_value=None, end_value=None, inclusive_start=True, inclusive_end=True)[source]

Bases: object

A range of values to restrict to in a row filter.

With only match cells that have values in this range.

Both the start and end value can be included or excluded in the range. By default, we include them both, but this can be changed with optional flags.

Parameters:
  • start_value (bytes) – The start of the range of values. If no value is used, it is interpreted as the empty string (inclusive) by the backend.
  • end_value (bytes) – The end of the range of values. If no value is used, it is interpreted as the infinite string (exclusive) by the backend.
  • inclusive_start (bool) – Boolean indicating if the start value should be included in the range (or excluded).
  • inclusive_end (bool) – Boolean indicating if the end value should be included in the range (or excluded).
to_pb()[source]

Converts the CellValueRange to a protobuf.

Return type:data_pb2.ValueRange
Returns:The converted current object.
class gcloud_bigtable.row.ColumnRange(column_family_id, start_column=None, end_column=None, inclusive_start=True, inclusive_end=True)[source]

Bases: object

A range of columns to restrict to in a row filter.

Both the start and end column can be included or excluded in the range. By default, we include them both, but this can be changed with optional flags.

Parameters:
  • column_family_id (str) – The column family that contains the columns. Must be of the form [_a-zA-Z0-9][-_.a-zA-Z0-9]*.
  • start_column (bytes) – The start of the range of columns. If no value is used, it is interpreted as the empty string (inclusive) by the backend.
  • end_column (bytes) – The end of the range of columns. If no value is used, it is interpreted as the infinite string (exclusive) by the backend.
  • inclusive_start (bool) – Boolean indicating if the start column should be included in the range (or excluded).
  • inclusive_end (bool) – Boolean indicating if the end column should be included in the range (or excluded).
to_pb()[source]

Converts the ColumnRange to a protobuf.

Return type:data_pb2.ColumnRange
Returns:The converted current object.
class gcloud_bigtable.row.ConditionalRowFilter(base_filter, true_filter=None, false_filter=None)[source]

Bases: object

Conditional filter

Executes one of two filters based on another filter. If the base_filter returns any cells in the row, then true_filter is executed. If not, then false_filter is executed.

Note

The base_filter does not execute atomically with the true and false filters, which may lead to inconsistent or unexpected results.

Additionally, executing a ConditionalRowFilter has poor performance on the server, especially when false_filter is set.

Parameters:
to_pb()[source]

Converts the ConditionalRowFilter to a protobuf.

Return type:data_pb2.RowFilter
Returns:The converted current object.
class gcloud_bigtable.row.Row(row_key, table, filter=None)[source]

Bases: object

Representation of a Google Cloud Bigtable Row.

Note

A Row 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(). If a filter is set on the Row, the mutations must have an associated state: True or False. The mutations will be applied conditionally, based on whether the filter matches any cells in the Row or not.

Parameters:
ALL_COLUMNS = <object object>

Sentinel value used to indicate all columns in a column family.

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_modification_rules()[source]

Removes all currently accumulated modifications on current row.

clear_mutations()[source]

Removes all currently accumulated mutations on the current row.

client

Getter for row’s client.

Return type:client.Client
Returns:The client that owns this row.
commit(timeout_seconds=None)[source]

Makes a MutateRow or CheckAndMutateRow 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.

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

Parameters:timeout_seconds (int) – Number of seconds for request time-out. If not passed, defaults to value set on row.
Return type:bool or NoneType
Returns:None if there is no filter, otherwise a 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.
commit_modifications(timeout_seconds=None)[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).

Parameters:timeout_seconds (int) – Number of seconds for request time-out. If not passed, defaults to value set on row.
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. For example:
{
    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(...)),
        ],
    },
}
delete(state=None)[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. Unset if the mutation is not conditional, otherwise True or False.
delete_cell(column_family_id, column, time_range=None, state=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.
  • state (bool) – (Optional) The state that the mutation should be applied in. Unset if the mutation is not conditional, otherwise True or False.
delete_cells(column_family_id, columns, time_range=None, state=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 Row.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. Unset if the mutation is not conditional, otherwise True or False.
filter

Getter for row’s filter.

Return type:RowFilter, RowFilterChain, RowFilterUnion, ConditionalRowFilter or NoneType
Returns:The filter for the row.
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.
row_key

Getter for row’s key.

Return type:bytes
Returns:The key for the row.
set_cell(column_family_id, column, value, timestamp=None, state=None)[source]

Sets a value in this row.

The cell is determined by the row_key of the Row and the column. The column must be in an existing column_family.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. Unset if the mutation is not conditional, otherwise True or False.
table

Getter for row’s table.

Return type:table.Table
Returns:The table stored on the row.
timeout_seconds

Getter for row’s default timeout seconds.

Return type:int
Returns:The timeout seconds default.
class gcloud_bigtable.row.RowFilter(row_key_regex_filter=None, family_name_regex_filter=None, column_qualifier_regex_filter=None, value_regex_filter=None, column_range_filter=None, timestamp_range_filter=None, value_range_filter=None, cells_per_row_offset_filter=None, cells_per_row_limit_filter=None, cells_per_column_limit_filter=None, row_sample_filter=None, strip_value_transformer=None)[source]

Bases: object

Basic filter to apply to cells in a row.

These values can be combined via RowFilterChain, RowFilterUnion and ConditionalRowFilter.

The regex filters must be valid RE2 patterns. See Google’s RE2 reference for the accepted syntax.

Note

At most one of the keyword arguments can be specified at once.

Note

For bytes regex filters (row_key, column_qualifier and value), special care need be used with the expression used. Since each of these properties can contain arbitrary bytes, the \C escape sequence must be used if a true wildcard is desired. The . character will not match the new line character \n, which may be present in a binary value.

Parameters:
  • row_key_regex_filter (bytes) – A regular expression (RE2) to match cells from rows with row keys that satisfy this regex. For a CheckAndMutateRowRequest, this filter is unnecessary since the row key is already specified.
  • family_name_regex_filter (str) – A regular expression (RE2) to match cells from columns in a given column family. For technical reasons, the regex must not contain the ':' character, even if it isnot being uses as a literal.
  • column_qualifier_regex_filter (bytes) – A regular expression (RE2) to match cells from column that match this regex (irrespective of column family).
  • value_regex_filter (bytes) – A regular expression (RE2) to match cells with values that match this regex.
  • column_range_filter (ColumnRange) – Range of columns to limit cells to.
  • timestamp_range_filter (TimestampRange) – Range of time that cells should match against.
  • value_range_filter (CellValueRange) – Range of cell values to filter for.
  • cells_per_row_offset_filter (int) – Skips the first N cells of the row.
  • cells_per_row_limit_filter (int) – Matches only the first N cells of the row.
  • cells_per_column_limit_filter (int) – Matches only the most recent N cells within each column. This filters a (family name, column) pair, based on timestamps of each cell.
  • row_sample_filter (float) – Non-deterministic filter. Matches all cells from a row with probability p, and matches no cells from the row with probability 1-p. (Here, the probability p is row_sample_filter.)
  • strip_value_transformer (bool) – If True, replaces each cell’s value with the empty string. As the name indicates, this is more useful as a transformer than a generic query / filter.
Raises:

TypeError if not exactly one value set in the constructor.
to_pb()[source]

Converts the RowFilter to a protobuf.

Return type:data_pb2.RowFilter
Returns:The converted current object.
class gcloud_bigtable.row.RowFilterChain(filters=None)[source]

Bases: object

Chain of row filters.

Sends rows through several filters in sequence. The filters are “chained” together to process a row. After the first filter is applied, the second is applied to the filtered output and so on for subsequent filters.

Parameters:filters (list) – List of RowFilter, RowFilterChain, RowFilterUnion and/or ConditionalRowFilter
to_pb()[source]

Converts the RowFilterChain to a protobuf.

Return type:data_pb2.RowFilter
Returns:The converted current object.
class gcloud_bigtable.row.RowFilterUnion(filters=None)[source]

Bases: object

Union of row filters.

Sends rows through several filters simultaneously, then merges / interleaves all the filtered results together.

If multiple cells are produced with the same column and timestamp, they will all appear in the output row in an unspecified mutual order.

Parameters:filters (list) – List of RowFilter, RowFilterChain, RowFilterUnion and/or ConditionalRowFilter
to_pb()[source]

Converts the RowFilterUnion to a protobuf.

Return type:data_pb2.RowFilter
Returns:The converted current object.
class gcloud_bigtable.row.TimestampRange(start=None, end=None)[source]

Bases: object

Range of time with inclusive lower and exclusive upper bounds.

Parameters:
  • start (datetime.datetime) – (Optional) The (inclusive) lower bound of the timestamp range. If omitted, defaults to Unix epoch.
  • end (datetime.datetime) – (Optional) The (exclusive) upper bound of the timestamp range. If omitted, defaults to “infinity” (no upper bound).
to_pb()[source]

Converts the TimestampRange to a protobuf.

Return type:data_pb2.TimestampRange
Returns:The converted current object.