Chapter 12. Thrift API and Filter Language

Chapter 12. Thrift API and Filter Language
Prev		Next

Table of Contents

12.1.1. General Filter String Syntax
12.1.2. Compound Filters and Operators
12.1.3. Order of Evaluation
12.1.4. Compare Operator
12.1.5. Comparator
12.1.6. Example PHP Client Program that uses the Filter Language
12.1.7. Example Filter Strings
12.1.8. Individual Filter Syntax

Apache Thrift is a cross-platform, cross-language development framework. HBase includes a Thrift API and filter language. The Thrift API relies on client and server processes. Documentation about the HBase Thrift API is located at http://wiki.apache.org/hadoop/Hbase/ThriftApi.

You can configure Thrift for secure authentication at the server and client side, by following the procedures in Section 8.1.4, “Client-side Configuration for Secure Operation - Thrift Gateway” and Section 8.1.5, “Configure the Thrift Gateway to Authenticate on Behalf of the Client”.

The rest of this chapter discusses the filter language provided by the Thrift API.

12.1. Filter Language

Thrift Filter Language was introduced in APache HBase 0.92. It allows you to perform server-side filtering when accessing HBase over Thrift or in the HBase shell. You can find out more about shell integration by using the scan help command in the shell.

You specify a filter as a string, which is parsed on the server to construct the filter.

12.1.1. General Filter String Syntax

A simple filter expression is expressed as a string:

“FilterName (argument, argument,... , argument)”

Keep the following syntax guidelines in mind.

Specify the name of the filter followed by the comma-separated argument list in parentheses.
If the argument represents a string, it should be enclosed in single quotes (').
Arguments which represent a boolean, an integer, or a comparison operator (such as <, >, or !=), should not be enclosed in quotes
The filter name must be a single word. All ASCII characters are allowed except for whitespace, single quotes and parentheses.
The filter’s arguments can contain any ASCII character. If single quotes are present in the argument, they must be escaped by an additional preceding single quote.

12.1.2. Compound Filters and Operators

Binary Operators

AND: If the AND operator is used, the key-vallue must satisfy both the filters.
OR: If the OR operator is used, the key-value must satisfy at least one of the filters.

Unary Operators

SKIP: For a particular row, if any of the key-values fail the filter condition, the entire row is skipped.
WHILE: For a particular row, key-values will be emitted until a key-value is reached t hat fails the filter condition.

Example 12.1. Compound Operators

You can combine multiple operators to create a hierarchy of filters, such as the following example:

(Filter1 AND Filter2) OR (Filter3 AND Filter4)

12.1.3. Order of Evaluation

Parentheses have the highest precedence.
The unary operators SKIP and WHILE are next, and have the same precedence.
The binary operators follow. AND has highest precedence, followed by OR.

Example 12.2. Precedence Example

Filter1 AND Filter2 OR Filter
is evaluated as
(Filter1 AND Filter2) OR Filter3

Filter1 AND SKIP Filter2 OR Filter3
is evaluated as
(Filter1 AND (SKIP Filter2)) OR Filter3

You can use parentheses to explicitly control the order of evaluation.

12.1.4. Compare Operator

The following compare operators are provided:

LESS (<)
LESS_OR_EQUAL (<=)
EQUAL (=)
NOT_EQUAL (!=)
GREATER_OR_EQUAL (>=)
GREATER (>)
NO_OP (no operation)

The client should use the symbols (<, <=, =, !=, >, >=) to express compare operators.

12.1.5. Comparator

A comparator can be any of the following:

BinaryComparator - This lexicographically compares against the specified byte array using Bytes.compareTo(byte[], byte[])
BinaryPrefixComparator - This lexicographically compares against a specified byte array. It only compares up to the length of this byte array.
RegexStringComparator - This compares against the specified byte array using the given regular expression. Only EQUAL and NOT_EQUAL comparisons are valid with this comparator
SubStringComparator - This tests if the given substring appears in a specified byte array. The comparison is case insensitive. Only EQUAL and NOT_EQUAL comparisons are valid with this comparator

The general syntax of a comparator is:ComparatorType:ComparatorValue

The ComparatorType for the various comparators is as follows:

BinaryComparator - binary
BinaryPrefixComparator - binaryprefix
RegexStringComparator - regexstring
SubStringComparator - substring

The ComparatorValue can be any value.

Example 12.3. Example 1

>, 'binary:abc' will match everything that is lexicographically greater than "abc"

Example 12.4. Example 2

=, 'binaryprefix:abc' will match everything whose first 3 characters are lexicographically equal to "abc"

Example 12.5. Example 3

!=, 'regexstring:ab*yz' will match everything that doesn't begin with "ab" and ends with "yz"

Example 12.6. Example 4

=, 'substring:abc123' will match everything that begins with the substring "abc123"

12.1.6. Example PHP Client Program that uses the Filter Language

<? $_SERVER['PHP_ROOT'] = realpath(dirname(__FILE__).'/..');
   require_once $_SERVER['PHP_ROOT'].'/flib/__flib.php';
   flib_init(FLIB_CONTEXT_SCRIPT);
   require_module('storage/hbase');
   $hbase = new HBase('<server_name_running_thrift_server>', <port on which thrift server is running>);
   $hbase->open();
   $client = $hbase->getClient();
   $result = $client->scannerOpenWithFilterString('table_name', "(PrefixFilter ('row2') AND (QualifierFilter (>=, 'binary:xyz'))) AND (TimestampsFilter ( 123, 456))");
   $to_print = $client->scannerGetList($result,1);
   while ($to_print) {
      print_r($to_print);
      $to_print = $client->scannerGetList($result,1);
    }
   $client->scannerClose($result);
?>

12.1.7. Example Filter Strings

“PrefixFilter (‘Row’) AND PageFilter (1) AND FirstKeyOnlyFilter ()” will return all key-value pairs that match the following conditions:
1. The row containing the key-value should have prefix “Row”
2. The key-value must be located in the first row of the table
3. The key-value pair must be the first key-value in the row

- “(RowFilter (=, ‘binary:Row 1’) AND TimeStampsFilter (74689, 89734)) OR ColumnRangeFilter (‘abc’, true, ‘xyz’, false))” will return all key-value pairs that match both the following conditions:
  - The key-value is in a row having row key “Row 1”
  - The key-value must have a timestamp of either 74689 or 89734.
  - Or it must match the following condition:
    The key-value pair must be in a column that is lexicographically >= abc and < xyz

“SKIP ValueFilter (0)” will skip the entire row if any of the values in the row is not 0

12.1.8. Individual Filter Syntax

KeyOnlyFilter

This filter doesn’t take any arguments. It returns only the key component of each key-value.

Syntax

```
KeyOnlyFilter ()
```

Example

```
KeyOnlyFilter ()"
```

FirstKeyOnlyFilter

This filter doesn’t take any arguments. It returns only the first key-value from each row.

Syntax

```
FirstKeyOnlyFilter ()
```

Example

```
FirstKeyOnlyFilter ()
```

PrefixFilter

This filter takes one argument – a prefix of a row key. It returns only those key-values present in a row that starts with the specified row prefix

Syntax

```
PrefixFilter (‘<row_prefix>’)
```

Example

```
PrefixFilter (‘Row’)
```

ColumnPrefixFilter

This filter takes one argument – a column prefix. It returns only those key-values present in a column that starts with the specified column prefix. The column prefix must be of the form: “qualifier”.

Syntax

ColumnPrefixFilter(‘<column_prefix>’)

Example

```
ColumnPrefixFilter(‘Col’)
```

MultipleColumnPrefixFilter

This filter takes a list of column prefixes. It returns key-values that are present in a column that starts with any of the specified column prefixes. Each of the column prefixes must be of the form: “qualifier”.

Syntax

MultipleColumnPrefixFilter(‘<column_prefix>’, ‘<column_prefix>’, …, ‘<column_prefix>’)

Example

MultipleColumnPrefixFilter(‘Col1’, ‘Col2’)

ColumnCountGetFilter

This filter takes one argument – a limit. It returns the first limit number of columns in the table.

Syntax

ColumnCountGetFilter
                        (‘<limit>’)

Example

```
ColumnCountGetFilter (4)
```

PageFilter

This filter takes one argument – a page size. It returns page size number of rows from the table.

Syntax

```
PageFilter (‘<page_size>’)
```

Example

```
PageFilter (2)
```

ColumnPaginationFilter

This filter takes two arguments – a limit and offset. It returns limit number of columns after offset number of columns. It does this for all the rows.

Syntax

ColumnPaginationFilter(‘<limit>’, ‘<offset>’)

Example

```
ColumnPaginationFilter (3, 5)
```

InclusiveStopFilter

This filter takes one argument – a row key on which to stop scanning. It returns all key-values present in rows up to and including the specified row.

Syntax

InclusiveStopFilter(‘<stop_row_key>’)

Example

```
InclusiveStopFilter ('Row2')
```

TimeStampsFilter

This filter takes a list of timestamps. It returns those key-values whose timestamps matches any of the specified timestamps.

Syntax

TimeStampsFilter (<timestamp>, <timestamp>, ... ,<timestamp>)

Example

TimeStampsFilter (5985489, 48895495, 58489845945)

RowFilter

This filter takes a compare operator and a comparator. It compares each row key with the comparator using the compare operator and if the comparison returns true, it returns all the key-values in that row.

Syntax

RowFilter (<compareOp>, ‘<row_comparator>’)

Example

```
RowFilter (<=, ‘xyz)
```

Family Filter

This filter takes a compare operator and a comparator. It compares each qualifier name with the comparator using the compare operator and if the comparison returns true, it returns all the key-values in that column.

Syntax

QualifierFilter (<compareOp>, ‘<qualifier_comparator>’)

Example

```
QualifierFilter (=, ‘Column1’)
```

QualifierFilter

Syntax

QualifierFilter (<compareOp>,‘<qualifier_comparator>’)

Example

```
QualifierFilter (=,‘Column1’)
```

ValueFilter

This filter takes a compare operator and a comparator. It compares each value with the comparator using the compare operator and if the comparison returns true, it returns that key-value.

Syntax

ValueFilter (<compareOp>,‘<value_comparator>’)

Example

```
ValueFilter (!=, ‘Value’)
```

DependentColumnFilter

This filter takes two arguments – a family and a qualifier. It tries to locate this column in each row and returns all key-values in that row that have the same timestamp. If the row doesn’t contain the specified column – none of the key-values in that row will be returned.

The filter can also take an optional boolean argument – dropDependentColumn. If set to true, the column we were depending on doesn’t get returned.

The filter can also take two more additional optional arguments – a compare operator and a value comparator, which are further checks in addition to the family and qualifier. If the dependent column is found, its value should also pass the value check and then only is its timestamp taken into consideration.

Syntax

DependentColumnFilter (‘<family>’,‘<qualifier>’, <boolean>, <compare operator>, ‘<value
                        comparator’)

DependentColumnFilter (‘<family>’,‘<qualifier>’, <boolean>)

DependentColumnFilter (‘<family>’,‘<qualifier>’)

Example

DependentColumnFilter (‘conf’, ‘blacklist’, false, >=, ‘zebra’)

DependentColumnFilter (‘conf’, 'blacklist', true)

DependentColumnFilter (‘conf’, 'blacklist')

SingleColumnValueFilter

This filter takes a column family, a qualifier, a compare operator and a comparator. If the specified column is not found – all the columns of that row will be emitted. If the column is found and the comparison with the comparator returns true, all the columns of the row will be emitted. If the condition fails, the row will not be emitted.

This filter also takes two additional optional boolean arguments – filterIfColumnMissing and setLatestVersionOnly

If the filterIfColumnMissing flag is set to true the columns of the row will not be emitted if the specified column to check is not found in the row. The default value is false.

If the setLatestVersionOnly flag is set to false, it will test previous versions (timestamps) too. The default value is true.

These flags are optional and if you must set neither or both.

Syntax

SingleColumnValueFilter(‘<family>’,‘<qualifier>’, <compare operator>, ‘<comparator>’, <filterIfColumnMissing_boolean>, <latest_version_boolean>)

SingleColumnValueFilter(‘<family>’, ‘<qualifier>, <compare operator>, ‘<comparator>’)

Example

SingleColumnValueFilter (‘FamilyA’, ‘Column1’, <=, ‘abc’, true, false)

SingleColumnValueFilter (‘FamilyA’, ‘Column1’, <=, ‘abc’)

SingleColumnValueExcludeFilter

This filter takes the same arguments and behaves same as SingleColumnValueFilter – however, if the column is found and the condition passes, all the columns of the row will be emitted except for the tested column value.

Syntax

SingleColumnValueExcludeFilter('<family>', '<qualifier>', <compare operator>, '<comparator>', <latest_version_boolean>, <filterIfColumnMissing_boolean>)

SingleColumnValueExcludeFilter('<family>', '<qualifier>', <compare operator>, '<comparator>')

Example

SingleColumnValueExcludeFilter (‘FamilyA’, ‘Column1’, ‘<=’, ‘abc’, ‘false’, ‘true’)

SingleColumnValueExcludeFilter (‘FamilyA’, ‘Column1’, ‘<=’, ‘abc’)

ColumnRangeFilter

This filter is used for selecting only those keys with columns that are between minColumn and maxColumn. It also takes two boolean variables to indicate whether to include the minColumn and maxColumn or not.

If you don’t want to set the minColumn or the maxColumn – you can pass in an empty argument.

Syntax

ColumnRangeFilter (‘<minColumn>’, <minColumnInclusive_bool>, ‘<maxColumn>’, <maxColumnInclusive_bool>)

Example

ColumnRangeFilter (‘abc’, true, ‘xyz’, false)

Prev		Next
11.4. C/C++ Apache HBase Client	Home	Chapter 13. Apache HBase Coprocessors