Get and Scan instances can be optionally configured with filters which are applied on the RegionServer.
Filters can be confusing because there are many different types, and it is best to approach them by understanding the groups of Filter functionality.
Structural Filters contain other Filters.
FilterList
represents a list of Filters with a relationship of FilterList.Operator.MUST_PASS_ALL
or
FilterList.Operator.MUST_PASS_ONE
between the Filters. The following example shows an 'or' between two
Filters (checking for either 'my value' or 'my other value' on the same attribute).
FilterList list = new FilterList(FilterList.Operator.MUST_PASS_ONE); SingleColumnValueFilter filter1 = new SingleColumnValueFilter( cf, column, CompareOp.EQUAL, Bytes.toBytes("my value") ); list.add(filter1); SingleColumnValueFilter filter2 = new SingleColumnValueFilter( cf, column, CompareOp.EQUAL, Bytes.toBytes("my other value") ); list.add(filter2); scan.setFilter(list);
SingleColumnValueFilter
can be used to test column values for equivalence (CompareOp.EQUAL
), inequality (CompareOp.NOT_EQUAL
), or ranges
(e.g., CompareOp.GREATER
). The folowing is example of testing equivalence a column to a String value "my value"...
SingleColumnValueFilter filter = new SingleColumnValueFilter( cf, column, CompareOp.EQUAL, Bytes.toBytes("my value") ); scan.setFilter(filter);
There are several Comparator classes in the Filter package that deserve special mention. These Comparators are used in concert with other Filters, such as Section 8.3.2.1, “SingleColumnValueFilter”.
RegexStringComparator supports regular expressions for value comparisons.
RegexStringComparator comp = new RegexStringComparator("my."); // any value that starts with 'my' SingleColumnValueFilter filter = new SingleColumnValueFilter( cf, column, CompareOp.EQUAL, comp ); scan.setFilter(filter);
See the Oracle JavaDoc for supported RegEx patterns in Java.
SubstringComparator can be used to determine if a given substring exists in a value. The comparison is case-insensitive.
SubstringComparator comp = new SubstringComparator("y val"); // looking for 'my value' SingleColumnValueFilter filter = new SingleColumnValueFilter( cf, column, CompareOp.EQUAL, comp ); scan.setFilter(filter);
See BinaryComparator.
As HBase stores data internally as KeyValue pairs, KeyValue Metadata Filters evaluate the existence of keys (i.e., ColumnFamily:Column qualifiers) for a row, as opposed to values the previous section.
FamilyFilter can be used to filter on the ColumnFamily. It is generally a better idea to select ColumnFamilies in the Scan than to do it with a Filter.
QualifierFilter can be used to filter based on Column (aka Qualifier) name.
ColumnPrefixFilter can be used to filter based on the lead portion of Column (aka Qualifier) names.
It is generally a better idea to use the startRow/stopRow methods on Scan for row selection, however RowFilter can also be used.
This is primarily used for rowcount jobs. See FirstKeyOnlyFilter.