Google Cloud Bigtable C++ Client  0.11.0
A C++ Client Library for Google Cloud Bigtable
Public Member Functions | Static Public Member Functions | List of all members
google::cloud::bigtable::v0::Filter Class Reference

Define the interfaces to create filter expressions. More...

#include <google/cloud/bigtable/filters.h>

Public Member Functions

 Filter (Filter &&) noexcept=default
 
Filteroperator= (Filter &&) noexcept=default
 
 Filter (Filter const &)=default
 
Filteroperator= (Filter const &)=default
 
::google::bigtable::v2::RowFilter const & as_proto () const &
 Return the filter expression as a protobuf. More...
 
::google::bigtable::v2::RowFilter && as_proto () &&
 Move out the underlying protobuf value. More...
 

Static Public Member Functions

static Filter PassAllFilter ()
 Return a filter that passes on all data. More...
 
static Filter BlockAllFilter ()
 Return a filter that blocks all data. More...
 
static Filter Latest (std::int32_t n)
 Return a filter that accepts only the last n values of each column. More...
 
static Filter FamilyRegex (std::string pattern)
 Return a filter that matches column families matching the given regexp. More...
 
static Filter ColumnRegex (std::string pattern)
 Return a filter that accepts only columns matching the given regexp. More...
 
static Filter ColumnRange (std::string family, std::string start, std::string end)
 Return a filter that accepts columns in the range [start, end) within the family column family. More...
 
static Filter ColumnName (std::string family, std::string column)
 Return the filter that accepts the named column within the family column family. More...
 
static Filter TimestampRangeMicros (std::int64_t start, std::int64_t end)
 Return a filter that accepts cells with timestamps in the range [start, end). More...
 
template<typename Rep1 , typename Period1 , typename Rep2 , typename Period2 >
static Filter TimestampRange (std::chrono::duration< Rep1, Period1 > start, std::chrono::duration< Rep2, Period2 > end)
 Return a filter that accepts cells with timestamps in the range [start, end). More...
 
static Filter RowKeysRegex (std::string pattern)
 Return a filter that matches keys matching the given regexp. More...
 
static Filter ValueRegex (std::string pattern)
 Return a filter that matches cells with values matching the given regexp. More...
 
static Filter ValueRange (std::string start, std::string end)
 Return filter matching values in the range [start, end). More...
 
static Filter CellsRowLimit (std::int32_t n)
 Return a filter that only accepts the first n cells in a row. More...
 
static Filter CellsRowOffset (std::int32_t n)
 Return a filter that skips the first n cells in a row. More...
 
static Filter RowSample (double probability)
 Return a filter that samples rows with a given probability. More...
 
static Filter StripValueTransformer ()
 Return a filter that transforms any values into the empty string. More...
 
static Filter ApplyLabelTransformer (std::string label)
 Returns a filter that applies a label to each value. More...
 
Less common range filters.

Cloud Bigtable range filters can include or exclude the limits of the range.

In most cases applications use [start, end) ranges, and the ValueRange() and ColumnRange() functions are offered to support the common case. For the less common cases where the application needs different ranges, the following functions are available.

static Filter ValueRangeLeftOpen (std::string start, std::string end)
 Return a filter that accepts values in the range [start, end). More...
 
static Filter ValueRangeRightOpen (std::string start, std::string end)
 Return a filter that accepts values in the range [start, end]. More...
 
static Filter ValueRangeClosed (std::string start, std::string end)
 Return a filter that accepts values in the range [start, end]. More...
 
static Filter ValueRangeOpen (std::string start, std::string end)
 Return a filter that accepts values in the range (start, end). More...
 
static Filter ColumnRangeRightOpen (std::string column_family, std::string start, std::string end)
 Return a filter that accepts columns in the range [start, end) within the column_family. More...
 
static Filter ColumnRangeLeftOpen (std::string column_family, std::string start, std::string end)
 Return a filter that accepts columns in the range (start, end] within the column_family. More...
 
static Filter ColumnRangeClosed (std::string column_family, std::string start, std::string end)
 Return a filter that accepts columns in the range [start, end] within the column_family. More...
 
static Filter ColumnRangeOpen (std::string column_family, std::string start, std::string end)
 Return a filter that accepts columns in the range (start, end) within the column_family. More...
 
Compound filters.

These filters compose several filters to build complex filter expressions.

static Filter Condition (Filter predicate, Filter true_filter, Filter false_filter)
 Returns a per-row conditional filter expression. More...
 
template<typename... FilterTypes>
static Filter Chain (FilterTypes &&... stages)
 Return a chain filter. More...
 
template<typename... FilterTypes>
static Filter Interleave (FilterTypes &&... streams)
 Return a filter that interleaves the results of many other filters. More...
 
static Filter Sink ()
 Return a filter that outputs all cells ignoring intermediate filters. More...
 

Detailed Description

Define the interfaces to create filter expressions.

Example:

// Get only data from the "fam" column family, and only the latest value.
auto filter = Filter::Chain(Filter::Family("fam"), Filter::Latest(1));
table->ReadRow("foo", std::move(filter));

Those filters that use regular expressions, expect the patterns to be in the RE2 syntax.

Note
Special care need be used with the expression used. Some of the filtered values (column names, row keys, cell values) are byte sequences, and 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, because . means [^\n] in RE2. As new line characters may be present in a binary value, you may need to explicitly match it using "\\n". The double escape is necessary because RE2 needs to get the escape sequence.

Definition at line 49 of file filters.h.

Constructor & Destructor Documentation

◆ Filter() [1/2]

google::cloud::bigtable::v0::Filter::Filter ( Filter &&  )
defaultnoexcept

◆ Filter() [2/2]

google::cloud::bigtable::v0::Filter::Filter ( Filter const &  )
default

Member Function Documentation

◆ ApplyLabelTransformer()

static Filter google::cloud::bigtable::v0::Filter::ApplyLabelTransformer ( std::string  label)
inlinestatic

Returns a filter that applies a label to each value.

Each value accepted by previous filters in modified to include the label.

Note
Currently, it is not possible to apply more than one label in a filter expression, that is, a chain can only contain a single ApplyLabelTransformer() filter. This limitation may be lifted in the future. It is possible to have multiple ApplyLabelTransformer filters in a Union() filter, though in this case, each copy of a cell gets a different label.
Parameters
labelthe label applied to each cell. The labels must be at most 15 characters long, and must match the [a-z0-9\\-]+ pattern. The server validates the filter and will return a grpc::StatusCode::INVALID_ARGUMENT if the label does not meet these requirements. This function makes no attempt to validate the label parameter before sending it to the server.

Definition at line 506 of file filters.h.

◆ as_proto() [1/2]

::google::bigtable::v2::RowFilter const& google::cloud::bigtable::v0::Filter::as_proto ( ) const &
inline

Return the filter expression as a protobuf.

Definition at line 632 of file filters.h.

◆ as_proto() [2/2]

::google::bigtable::v2::RowFilter&& google::cloud::bigtable::v0::Filter::as_proto ( ) &&
inline

Move out the underlying protobuf value.

Definition at line 635 of file filters.h.

◆ BlockAllFilter()

static Filter google::cloud::bigtable::v0::Filter::BlockAllFilter ( )
inlinestatic

Return a filter that blocks all data.

Definition at line 64 of file filters.h.

◆ CellsRowLimit()

static Filter google::cloud::bigtable::v0::Filter::CellsRowLimit ( std::int32_t  n)
inlinestatic

Return a filter that only accepts the first n cells in a row.

Note that cells might be repeated, such as when interleaving the results of multiple filters via the Interleave() function. Furthermore, this filter apples to the cells within a row; if there are multiple column families and/or columns in a row, the order is:

  • All the cells for a column family appear together, but there is no guarantee on the order of the column families. Furthermore, column families may appear in different orders in different rows.
  • Within a column family, the cells are ordered by column name, where column names are sorted lexicographically.
  • Within a column, the cells appear in descending order by timestamp.

The server rejects filters where n <= 0, any ReadRows() request containing such a filter fails with grpc::StatusCode::INVALID_ARGUMENT. This function does not perform any local validation of n.

Definition at line 284 of file filters.h.

◆ CellsRowOffset()

static Filter google::cloud::bigtable::v0::Filter::CellsRowOffset ( std::int32_t  n)
inlinestatic

Return a filter that skips the first n cells in a row.

Note that cells might be repeated, such as when interleaving the results of multiple filters via the Interleave() function. Furthermore, this filter apples to the cells within a row; if there are multiple column families and/or columns in a row, the order is:

  • All the cells for a column family appear together, but there is no guarantee on the order of the column families. Furthermore, column families may appear in different orders in different rows.
  • Within a column family, the cells are ordered by column name, where column names are sorted lexicographically.
  • Within a column, the cells appear in descending order by timestamp.

The server rejects filters where n <= 0, any ReadRows() request containing such a filter fails with grpc::StatusCode::INVALID_ARGUMENT. This function does not perform any local validation of n.

Definition at line 308 of file filters.h.

◆ Chain()

template<typename... FilterTypes>
static Filter google::cloud::bigtable::v0::Filter::Chain ( FilterTypes &&...  stages)
inlinestatic

Return a chain filter.

The filter returned by this function acts like a pipeline. The output row from each stage is passed on as input for the next stage.

Template Parameters
FilterTypesthe type of the filter arguments. They must all be convertible to Filter.
Parameters
stagesthe filter stages. The filter must contain at least two stages. The server validates each stage, and will reject them as described in their corresponding function. The server may also impose additional restrictions on the composition of the Chain. This function makes no attempt at validating the stages locally, the Chain filter is sent as-is it to the server.

Definition at line 557 of file filters.h.

◆ ColumnName()

static Filter google::cloud::bigtable::v0::Filter::ColumnName ( std::string  family,
std::string  column 
)
inlinestatic

Return the filter that accepts the named column within the family column family.

This function makes no attempt to validate the column family or column range before sending them to the server.

Definition at line 147 of file filters.h.

◆ ColumnRange()

static Filter google::cloud::bigtable::v0::Filter::ColumnRange ( std::string  family,
std::string  start,
std::string  end 
)
inlinestatic

Return a filter that accepts columns in the range [start, end) within the family column family.

The column range must be non-empty, i.e., start must be strictly smaller than end. The server will reject empty ranges with a grpc::StatusCode::INVALID_ARGUMENT status code. This function makes no attempt to validate the column family or column range before sending them to the server.

Definition at line 134 of file filters.h.

◆ ColumnRangeClosed()

static Filter google::cloud::bigtable::v0::Filter::ColumnRangeClosed ( std::string  column_family,
std::string  start,
std::string  end 
)
inlinestatic

Return a filter that accepts columns in the range [start, end] within the column_family.

The range must be non-empty. The server will reject empty ranges with a grpc::StatusCode::INVALID_ARGUMENT error. This function makes no attempt to validate the timestamp range before sending it to the server.

Definition at line 445 of file filters.h.

◆ ColumnRangeLeftOpen()

static Filter google::cloud::bigtable::v0::Filter::ColumnRangeLeftOpen ( std::string  column_family,
std::string  start,
std::string  end 
)
inlinestatic

Return a filter that accepts columns in the range (start, end] within the column_family.

The range must be non-empty. The server will reject empty ranges with a grpc::StatusCode::INVALID_ARGUMENT error. This function makes no attempt to validate the timestamp range before sending it to the server.

Definition at line 427 of file filters.h.

◆ ColumnRangeOpen()

static Filter google::cloud::bigtable::v0::Filter::ColumnRangeOpen ( std::string  column_family,
std::string  start,
std::string  end 
)
inlinestatic

Return a filter that accepts columns in the range (start, end) within the column_family.

The range must be non-empty. The server will reject empty ranges with a grpc::StatusCode::INVALID_ARGUMENT error. This function makes no attempt to validate the timestamp range before sending it to the server.

Definition at line 463 of file filters.h.

◆ ColumnRangeRightOpen()

static Filter google::cloud::bigtable::v0::Filter::ColumnRangeRightOpen ( std::string  column_family,
std::string  start,
std::string  end 
)
inlinestatic

Return a filter that accepts columns in the range [start, end) within the column_family.

The range must be non-empty. The server will reject empty ranges with a grpc::StatusCode::INVALID_ARGUMENT error. This function makes no attempt to validate the timestamp range before sending it to the server.

Definition at line 409 of file filters.h.

◆ ColumnRegex()

static Filter google::cloud::bigtable::v0::Filter::ColumnRegex ( std::string  pattern)
inlinestatic

Return a filter that accepts only columns matching the given regexp.

Parameters
patternthe regular expression. It must be a valid RE2 pattern. The server rejects filters with an invalid pattern with a grpc::StatusCode::INVALID_ARGUMENT status code. This function makes no attempt to validate the pattern before sending it to the server.
Note
Special care need be used with the expression used. A column name is a byte sequence, and 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, because . means [^\n] in RE2. As new line characters may be present in a binary value, you may need to explicitly match it using "\\n". The double escape is necessary because RE2 needs to get the escape sequence.

Definition at line 118 of file filters.h.

◆ Condition()

static Filter google::cloud::bigtable::v0::Filter::Condition ( Filter  predicate,
Filter  true_filter,
Filter  false_filter 
)
inlinestatic

Returns a per-row conditional filter expression.

For each row the predicate filter is evaluated, if it returns any cells, then the cells returned by true_filter are returned, otherwise the cells from false_filter are returned.

The server validates the tree of filters, and rejects them if any contain invalid values. The server may impose additional restrictions on the resulting collection of filters. This function makes no attempt to validate the input before sending it to the server.

Definition at line 531 of file filters.h.

◆ FamilyRegex()

static Filter google::cloud::bigtable::v0::Filter::FamilyRegex ( std::string  pattern)
inlinestatic

Return a filter that matches column families matching the given regexp.

Parameters
patternthe regular expression. It must be a valid RE2 pattern. For technical reasons, the regex must not contain the ':' character, even if it is not being used as a literal. The server rejects filters with invalid patterns, including patterns containing the ':' character. The server fails the ReadRows() request with a grpc::StatusCode::INVALID_ARGUMENT status code. This function makes no attempt to validate the pattern before sending it to the server.

Definition at line 95 of file filters.h.

◆ Interleave()

template<typename... FilterTypes>
static Filter google::cloud::bigtable::v0::Filter::Interleave ( FilterTypes &&...  streams)
inlinestatic

Return a filter that interleaves the results of many other filters.

This filter executes each stream in parallel and then merges the results by interleaving the output from each stream. The proto file has a nice illustration in the documentation of google.bigtable.v2.RowFilter.Interleave.

In brief, if the input cells are c1, c2, c3, ..., and you have three subfilters S1, S2, and S3, the output of Interleave(S1, S2, S3) is: S1(c1), S2(c1), S3(c1), S1(d2), S2(d2), S3(c2), S1(c3), S2(c3), S3(c2), ... where some of the Si(c_j) values may be empty if the filter discards the cell altogether.

Template Parameters
FilterTypesthe type of the filter arguments. They must all be convertible for Filter.
Parameters
streamsthe filters to interleave. The filter must contain at least two streams. The server validates each stream, and will reject them as described in their corresponding function. The server may also impose additional restrictions on the overall composition of the Interleave filter. This function makes no attempt at validating the streams locally, the Interleave filter is sent as-is to the server.

Definition at line 600 of file filters.h.

◆ Latest()

static Filter google::cloud::bigtable::v0::Filter::Latest ( std::int32_t  n)
inlinestatic

Return a filter that accepts only the last n values of each column.

The server rejects filters where n <= 0, any ReadRows() request containing such a filter fails with grpc::StatusCode::INVALID_ARGUMENT. This function does not perform any local validation of n.

Definition at line 77 of file filters.h.

◆ operator=() [1/2]

Filter& google::cloud::bigtable::v0::Filter::operator= ( Filter &&  )
defaultnoexcept

◆ operator=() [2/2]

Filter& google::cloud::bigtable::v0::Filter::operator= ( Filter const &  )
default

◆ PassAllFilter()

static Filter google::cloud::bigtable::v0::Filter::PassAllFilter ( )
inlinestatic

Return a filter that passes on all data.

Definition at line 57 of file filters.h.

◆ RowKeysRegex()

static Filter google::cloud::bigtable::v0::Filter::RowKeysRegex ( std::string  pattern)
inlinestatic

Return a filter that matches keys matching the given regexp.

Parameters
patternthe regular expression. It must be a valid RE2 pattern. More details at https://github.com/google/re2/wiki/Syntax
Note
Special care need be used with the expression used. A row key is a byte sequence, and 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, because . means [^\n] in RE2. As new line characters may be present in a binary value, you may need to explicitly match it using "\\n". The double escape is necessary because RE2 needs to get the escape sequence.

Definition at line 227 of file filters.h.

◆ RowSample()

static Filter google::cloud::bigtable::v0::Filter::RowSample ( double  probability)
inlinestatic

Return a filter that samples rows with a given probability.

The server rejects filters where probability is outside the range (0.0, 1.0). Any ReadRows() request containing such a filter fails with grpc::StatusCode::INVALID_ARGUMENT. This function does not perform any local validation of probability.

Parameters
probabilitythe probability that any row will be selected. It must be in the range (0.0, 1.0).

Definition at line 325 of file filters.h.

◆ Sink()

static Filter google::cloud::bigtable::v0::Filter::Sink ( )
inlinestatic

Return a filter that outputs all cells ignoring intermediate filters.

Please read the documentation in the proto file for a detailed description. In short, this is an advanced filter to facilitate debugging. You can explore the intermediate results of a complex filter expression by injecting a filter of this type.

Definition at line 624 of file filters.h.

◆ StripValueTransformer()

static Filter google::cloud::bigtable::v0::Filter::StripValueTransformer ( )
inlinestatic

Return a filter that transforms any values into the empty string.

As the name indicates, this acts as a transformer on the data, replacing any values with the empty string.

Definition at line 480 of file filters.h.

◆ TimestampRange()

template<typename Rep1 , typename Period1 , typename Rep2 , typename Period2 >
static Filter google::cloud::bigtable::v0::Filter::TimestampRange ( std::chrono::duration< Rep1, Period1 >  start,
std::chrono::duration< Rep2, Period2 >  end 
)
inlinestatic

Return a filter that accepts cells with timestamps in the range [start, end).

The function accepts any instantiation of std::chrono::duration<> for the start and end parameters. For example:

using namespace std::chrono_literals; // C++14
auto r1 = bigtable::Filter::TimestampRange(10ms, 500ms);
auto r2 = bigtable::Filter::TimestampRange(10min, 10min + 2s);

The timestamp range must be non-empty, i.e. start must be strictly smaller than end. The server will reject empty ranges with a grpc::StatusCode::INVALID_ARGUMENT error. This function makes no attempt to validate the timestamp range before sending it to the server.

Template Parameters
Rep1a placeholder to match the Rep tparam for start type, the semantics of this template parameter are documented in std::chrono::duration<> (in brief, the underlying arithmetic type used to store the number of ticks), for our purposes it is simply a formal parameter.
Rep2similar formal parameter for the type of end.
Period1a placeholder to match the Period tparam for start type, the semantics of this template parameter are documented in std::chrono::duration<> (in brief, the length of the tick in seconds, expressed as a std::ratio<>), for our purposes it is simply a formal parameter.
Period2similar formal parameter for the type of end.
See also
std::chrono::duration<> for more details.

Definition at line 206 of file filters.h.

◆ TimestampRangeMicros()

static Filter google::cloud::bigtable::v0::Filter::TimestampRangeMicros ( std::int64_t  start,
std::int64_t  end 
)
inlinestatic

Return a filter that accepts cells with timestamps in the range [start, end).

The timestamp range must be non-empty, i.e. start must be strictly smaller than end. The server will reject empty ranges with a grpc::StatusCode::INVALID_ARGUMENT status code. This function makes no attempt to validate the timestamp range before sending it to the server.

Definition at line 162 of file filters.h.

◆ ValueRange()

static Filter google::cloud::bigtable::v0::Filter::ValueRange ( std::string  start,
std::string  end 
)
inlinestatic

Return filter matching values in the range [start, end).

See also
ValueRangeRightOpen() for more details.

Definition at line 262 of file filters.h.

◆ ValueRangeClosed()

static Filter google::cloud::bigtable::v0::Filter::ValueRangeClosed ( std::string  start,
std::string  end 
)
inlinestatic

Return a filter that accepts values in the range [start, end].

The range must be non-empty. The server will reject empty ranges with a grpc::StatusCode::INVALID_ARGUMENT error. This function makes no attempt to validate the timestamp range before sending it to the server.

Definition at line 378 of file filters.h.

◆ ValueRangeLeftOpen()

static Filter google::cloud::bigtable::v0::Filter::ValueRangeLeftOpen ( std::string  start,
std::string  end 
)
inlinestatic

Return a filter that accepts values in the range [start, end).

The range must be non-empty. The server will reject empty ranges with a grpc::StatusCode::INVALID_ARGUMENT error. This function makes no attempt to validate the timestamp range before sending it to the server.

Definition at line 348 of file filters.h.

◆ ValueRangeOpen()

static Filter google::cloud::bigtable::v0::Filter::ValueRangeOpen ( std::string  start,
std::string  end 
)
inlinestatic

Return a filter that accepts values in the range (start, end).

The range must be non-empty. The server will reject empty ranges with a grpc::StatusCode::INVALID_ARGUMENT error. This function makes no attempt to validate the timestamp range before sending it to the server.

Definition at line 393 of file filters.h.

◆ ValueRangeRightOpen()

static Filter google::cloud::bigtable::v0::Filter::ValueRangeRightOpen ( std::string  start,
std::string  end 
)
inlinestatic

Return a filter that accepts values in the range [start, end].

The range must be non-empty. The server will reject empty ranges with a grpc::StatusCode::INVALID_ARGUMENT error. This function makes no attempt to validate the timestamp range before sending it to the server.

Definition at line 363 of file filters.h.

◆ ValueRegex()

static Filter google::cloud::bigtable::v0::Filter::ValueRegex ( std::string  pattern)
inlinestatic

Return a filter that matches cells with values matching the given regexp.

Parameters
patternthe regular expression. It must be a valid RE2 pattern. The server rejects filters with an invalid pattern with a grpc::StatusCode::INVALID_ARGUMENT status code. This function makes no attempt to validate the timestamp range before sending it to the server.
Note
Special care need be used with the expression used. A cell value is a byte sequence, and 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, because . means [^\n] in RE2. As new line characters may be present in a binary value, you may need to explicitly match it using "\\n". The double escape is necessary because RE2 needs to get the escape sequence.

Definition at line 251 of file filters.h.