Index: src/docbkx/book.xml
===================================================================
--- src/docbkx/book.xml (revision 1237198)
+++ src/docbkx/book.xml (working copy)
@@ -1546,11 +1546,90 @@
ColumnPrefixFilter can be used
to filter based on the lead portion of Column (aka Qualifier) names.
+ A ColumnPrefixFilter seeks ahead to the first column matching the prefix in each row and for each involved column family. It can be used to efficiently
+ get a subset of the columns in very wide rows.
+
+ Note: The same column qualifier can used in different column families. This filter returns all matching columns.
+
+ Example: Find all columns in a row and family that start with "abc"
+
+HTableInterface t = ...;
+byte[] row = ...;
+byte[] family = ...;
+byte[] prefix = Bytes.toBytes("abc");
+Scan scan = new Scan(row, row); // (optional) limit to one row
+scan.addFamily(family); // (optional) limit to one family
+Filter f = new ColumnPrefixFilter(prefix);
+scan.setFilter(f);
+scan.setBatch(10); // set this if there could be many columns returned
+ResultScanner rs = t.getScanner(scan);
+for (Result r = rs.next(); r != null; r = rs.next()) {
+ for (KeyValue kv : r.raw()) {
+ // each kv represents a column
+ }
+}
+rs.close();
+
+
+ MultipleColumnPrefixFilter
+ MultipleColumnPrefixFilter behaves like ColumnPrefixFilter
+ but allows specifying multiple prefixes.
+
+ Like ColumnPrefixFilter, MultipleColumnPrefixFilter efficiently seeks ahead to the first column matching the lowest prefix and also seeks past ranges of columns between prefixes.
+ It can be used to efficiently get discontinuous set of columns from very wide rows.
+
+ Example: Find all columns in a row and family that start with "abc" or "xyz"
+
+HTableInterface t = ...;
+byte[] row = ...;
+byte[] family = ...;
+byte[] prefixes = new byte[][] {Bytes.toBytes("abc"), Bytes.toBytes("xyz")};
+Scan scan = new Scan(row, row); // (optional) limit to one row
+scan.addFamily(family); // (optional) limit to one family
+Filter f = new MultipleColumnPrefixFilter(prefixes);
+scan.setFilter(f);
+scan.setBatch(10); // set this if there could be many columns returned
+ResultScanner rs = t.getScanner(scan);
+for (Result r = rs.next(); r != null; r = rs.next()) {
+ for (KeyValue kv : r.raw()) {
+ // each kv represents a column
+ }
+}
+rs.close();
+
+
+ ColumnRangeFilter
- Use ColumnRangeFilter to get a column 'slice':
- i.e. if you have a million columns in a row but you only want to look at columns bbbb-bbbd.
+ A ColumnRangeFilter allows efficient intra row scanning.
+ A ColumnRangeFilter can seek ahead to the first matching column for each involved column family. It can be used to efficiently
+ get a 'slice' of the columns of a very wide row.
+ i.e. you have a million columns in a row but you only want to look at columns bbbb-bbdd.
+
+ Note: The same column qualifier can used in different column families. This filter returns all matching columns.
+
+ Example: Find all columns in a row and family between "bbbb" (inclusive) and "bbdd" (inclusive)
+
+HTableInterface t = ...;
+byte[] row = ...;
+byte[] family = ...;
+byte[] startColumn = Bytes.toBytes("bbbb");
+byte[] endColumn = Bytes.toBytes("bbdd");
+Scan scan = new Scan(row, row); // (optional) limit to one row
+scan.addFamily(family); // (optional) limit to one family
+Filter f = new ColumnRangeFilter(startColumn, true, endColumn, true);
+scan.setFilter(f);
+scan.setBatch(10); // set this if there could be many columns returned
+ResultScanner rs = t.getScanner(scan);
+for (Result r = rs.next(); r != null; r = rs.next()) {
+ for (KeyValue kv : r.raw()) {
+ // each kv represents a column
+ }
+}
+rs.close();
+
+Note: Introduced in HBase 0.92