Index: src/docbkx/book.xml
===================================================================
--- src/docbkx/book.xml (revision 1176904)
+++ src/docbkx/book.xml (working copy)
@@ -1236,16 +1236,139 @@
see the batch methods on HTable.
- Filters
- Get and Scan instances can be
- optionally configured with filters which are applied on the RegionServer.
-
- External ClientsInformation on non-Java clients and custom protocols is covered in
+
+ Client Filters
+ 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
+ Structural Filters contain other Filters.
+ FilterList
+ 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);
+
+
+
+
+ Column Value
+ SingleColumnValueFilter
+ 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);
+
+
+
+
+ Column Value Comparators
+ There are several Comparator classes in the Filter package that deserve special mention.
+ These Comparators are used in concert with other Filters, such as .
+
+ RegexStringComparator
+ 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
+ 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);
+
+
+ BinaryPrefixComparator
+ See BinaryPrefixComparator.
+
+ BinaryComparator
+ See BinaryComparator.
+
+
+ KeyValue Metadata
+ 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
+ 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
+ QualifierFilter can be used
+ to filter based on Column (aka Qualifier) name.
+
+
+ ColumnPrefixFilter
+ ColumnPrefixFilter can be used
+ to filter based on the lead portion of Column (aka Qualifier) names.
+
+
+
+ RowKey
+ RowFilter
+ It is generally a better idea to use the startRow/stopRow methods on Scan for row selection, however
+ RowFilter can also be used.
+
+
+ Utility
+ FirstKeyOnlyFilter
+ This is primarily used for rowcount jobs.
+ See FirstKeyOnlyFilter.
+
+
+ MasterHMaster is the implementation of the Master Server. The Master server