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.
- column_family_id (str) – The column family that contains the columns. Must
be of the form
-
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, thentrue_filter
is executed. If not, thenfalse_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 whenfalse_filter
is set.Parameters: - base_filter (
RowFilter
,RowFilterChain
,RowFilterUnion
orConditionalRowFilter
) – The filter to condition on before executing the true/false filters. - true_filter (
RowFilter
,RowFilterChain
,RowFilterUnion
orConditionalRowFilter
) – (Optional) The filter to execute if there are any cells matchingbase_filter
. If not provided, no results will be returned in the true case. - false_filter (
RowFilter
,RowFilterChain
,RowFilterUnion
orConditionalRowFilter
) – (Optional) The filter to execute if there are no cells matchingbase_filter
. If not provided, no results will be returned in the false case.
-
to_pb
()[source]¶ Converts the
ConditionalRowFilter
to a protobuf.Return type: data_pb2.RowFilter
Returns: The converted current object.
- base_filter (
-
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 theset_cell()
,delete()
,delete_cell()
anddelete_cells()
methods. To actually send these mutations to the Google Cloud Bigtable API, you must callcommit()
. If afilter
is set on theRow
, the mutations must have an associated state:True
orFalse
. The mutations will be applied conditionally, based on whether the filter matches any cells in theRow
or not.Parameters: - row_key (bytes) – The key for the current row.
- table (
table.Table
) – The table that owns the row. - filter (
RowFilter
,RowFilterChain
,RowFilterUnion
orConditionalRowFilter
) – (Optional) Filter to be used for conditional mutations. If a filter is set, then theRow
will accumulate mutations for either aTrue
orFalse
state. Whencommit()
-ed, the mutations for theTrue
state will be applied if the filter matches any cells in the row, otherwise theFalse
state will be.
-
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, callcommit()
.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.
- column_family_id (str) – The column family that contains the column.
Must be of the form
-
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
orCheckAndMutateRow
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 theRow
or not. (Each method which adds a mutation has astate
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
orNoneType
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()
andincrement_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, callcommit()
.Parameters: state (bool) – (Optional) The state that the mutation should be applied in. Unset if the mutation is not conditional, otherwise True
orFalse
.
-
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, callcommit()
.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
orFalse
.
- column_family_id (str) – The column family that contains the column
or columns with cells being deleted. Must be
of the form
-
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, callcommit()
.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
ofstr
/unicode
, orobject
) – The columns within the column family that will have cells deleted. IfRow.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
orFalse
.
- column_family_id (str) – The column family that contains the column
or columns with cells being deleted. Must be
of the form
-
filter
¶ Getter for row’s filter.
Return type: RowFilter
,RowFilterChain
,RowFilterUnion
,ConditionalRowFilter
orNoneType
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, callcommit()
.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.
- column_family_id (str) – The column family that contains the column.
Must be of the form
-
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 theRow
and thecolumn
. Thecolumn
must be in an existingcolumn_family.ColumnFamily
(as determined bycolumn_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, callcommit()
.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
orFalse
.
- column_family_id (str) – The column family that contains the column.
Must be of the form
-
table
¶ Getter for row’s table.
Return type: table.Table
Returns: The table stored on the row.
-
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
andConditionalRowFilter
.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
andvalue
), 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.- row_key_regex_filter (bytes) – A regular expression (RE2) to match cells from
rows with row keys that satisfy this regex.
For a
-
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/orConditionalRowFilter
-
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/orConditionalRowFilter
-
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.
- start (