Thrift API 和过滤器语言
- 103. 过滤器语言

Thrift API 和过滤器语言

贡献者：xixici

Apache Thrift 是跨平台跨语言的开发框架。HBase 包含了 Thrift API 和过滤语言。Thrift API 依赖于客户端和服务器进程。

你可以在服务端和客户端维 Thrift 设置安全身份验证，参照 Client-side Configuration for Secure Operation - Thrift Gateway 和 Configure the Thrift Gateway to Authenticate on Behalf of the Client.

接下来，讨论 Thrift API 所提供的过滤器语言。

103. 过滤器语言

Thrift 过滤语言在 HBase 0.92 版本引入. 提供了通过在 HBase 上使用 Thrift 或使用 HBase Shell 来进行服务端过滤. 你可以在 Shell 中，使用scan help查看详细信息.

将过滤器写成字符串，在服务端解析成过滤器。

103.1. 常规过滤字符串语法

字符串形式过滤器:

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

记住以下语法规则：

指定过滤器的名称，后跟括号中以逗号分隔的参数列表。

如果参数是字符串，应该用单引号'包括。
布尔值, 整形, 比较符 ( <, >, !=)不需要用引号包括。
过滤器名称必须是单个单词。除空格，单引号和括号外，允许使用所有 ASCII 字符。
过滤器的参数可以包含任何 ASCII 字符。如果参数中存在单引号，则必须通过附加的前一个单引号对其进行转义。

103.2. 复合过滤器和运算符

二元运算符

AND

使用 AND ，键值对必须满足两端过滤器

OR

使用 OR，键值对至少满足一端过滤器

一元运算符

SKIP

对特定行，如果键值对不满足过滤，则跳过此行

WHILE

对特定行, 键值将通过，直至过滤条件不满足为止。

Example 29. 复合运算符

你可以组合运算符来创建层次结构的过滤器如：

(Filter1 AND Filter2) OR (Filter3 AND Filter4)

103.3. 运算次序

括号有着最高优先级
然后是一元运算符 SKIP 和 WHILE ，优先级相同
二元运算符 AND 最高, 其次 OR

Example 30. 优先级示例

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

你可以使用括号精确控制运算顺序

103.4. 比较运算符

以下比较运算符：

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

客户端应采用(<, ⇐, =, !=, >, >=) 表示比较

103.5. 比较器

比较器可以如下任一种：

BinaryComparator - 按字典顺序比较特定字节数组，使用 Bytes.compareTo(byte[], byte[])
BinaryPrefixComparator - 按字典顺序比较特定字节数组，只比较字节数组长度.
RegexStringComparator - 使用给定正则表达式，比较特定字节组。在这种比较器中，只有 EQUAL 和 NOT_EQUAL 有效
SubStringComparator - 给定字符子串是否出现在特定字节组中。不区分大小写。在这种比较器中，只有 EQUAL 和 NOT_EQUAL 有效

比较器一般语法规则: ComparatorType:ComparatorValue

不同比较器的不同比较类型：

BinaryComparator - binary 二进制
BinaryPrefixComparator - binaryprefix 二进制长度
RegexStringComparator - regexstring 正则表达式
SubStringComparator - substring 子字符串

ComparatorValue 可以任意值

比较示例：

binary:abc 匹配字典顺序大于”abc”
binaryprefix:abc 匹配字典书序前 3 字符等于 “abc”
regexstring:ab*yz 匹配以 ab 开头，已 yz 结尾的内容
substring:abc123 匹配所有以”abc123”开头的内容

103.6. PHP 客户端使用示例

<?
  $_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);
?>

103.7. 过滤器示例

"PrefixFilter ('Row') AND PageFilter (1) AND FirstKeyOnlyFilter ()" 会返回符合下列条件的所有键值对
1. 键值对所在行有前缀 Row
2. 键值对必须处于第一行
3. 键值对必须是第一个键值
"(RowFilter (=, 'binary:Row 1') AND TimeStampsFilter (74689, 89734)) OR ColumnRangeFilter ('abc', true, 'xyz', false))" 会返回符合下列条件的所有键值对
- 键值对所在行有前缀 Row 1
- 键值必须具有时间戳 74689 或者 89734.
- 或者满足一下条件:
  - 键值对必须位于字典序 >= abc 和 < xyz 之间
"SKIP ValueFilter (0)" 如果行中任何值部位 0, 则跳过

103.8. 单个过滤器语法

KeyOnlyFilter

此过滤器不带任何参数。它仅返回每个键值的关键组件。

FirstKeyOnlyFilter

此过滤器不带任何参数。它仅返回每行的第一个键值。

PrefixFilter

此过滤器采用一个参数 - 行键的前缀。它仅返回以指定行前缀开头的行中存在的键值

ColumnPrefixFilter

此过滤器采用一个参数 - 列前缀。它仅返回以指定列前缀开头的列中存在的键值。列前缀的格式必须为： “qualifier”.

MultipleColumnPrefixFilter

此过滤器采用列前缀列表。它返回以任何指定列前缀开头的列中存在的键值。每个列前缀必须采用以下形式：“qualifier”.

ColumnCountGetFilter

此过滤器采用一个参数 - 一个限制。它返回表中的第一个限制列数。

PageFilter

此过滤器采用一个参数 - 页面大小。它返回表中的页面大小行数。

ColumnPaginationFilter

此过滤器有两个参数 - 限制和偏移。它返回偏移列数后的列数限制。它为所有行执行此操作。

InclusiveStopFilter

此过滤器使用一个参数 - 要停止扫描的行键。它返回行中存在的所有键值，包括指定的行。

TimeStampsFilter

此过滤器采用时间戳列表。它返回时间戳与任何指定时间戳匹配的键值。

RowFilter

该过滤器采用比较运算符和比较器。它使用 compare 运算符将每个行键与比较器进行比较，如果比较返回 true，则返回该行中的所有键值。

Family Filter

该过滤器采用比较运算符和比较器。它使用比较运算符将每个列族名称与比较器进行比较，如果比较返回 true，则返回该列族中的所有单元格。

QualifierFilter

该过滤器采用比较运算符和比较器。它使用 compare 运算符将每个限定符名称与比较器进行比较，如果比较返回 true，则返回该列中的所有键值。

ValueFilter

该过滤器采用比较运算符和比较器。它使用比较运算符将每个值与比较器进行比较，如果比较返回 true，则返回该键值。

DependentColumnFilter

此过滤器有两个参数 - 族和限定符。它尝试在每一行中找到此列，并返回该行中具有相同时间戳的所有键值。如果该行不包含指定的列 - 将返回该行中的任何键值。

SingleColumnValueFilter

该过滤器采用列族，限定符，比较运算符和比较器。如果未找到指定的列 - 将发出该行的所有列。如果找到该列并且与比较器的比较返回 true，则将发出该行的所有列。如果条件失败，则不会发出该行。

SingleColumnValueExcludeFilter

此过滤器采用相同的参数，其行为与 SingleColumnValueFilter 相同 - 但是，如果找到该列并且条件通过，则除了测试的列值之外，将发出该行的所有列。

ColumnRangeFilter

此过滤器仅用于选择列在 minColumn 和 maxColumn 之间的键。它还需要两个布尔变量来指示是否包含 minColumn 和 maxColumn。

Thrift API 和过滤器语言 - Thrift API and Filter Language