# Thrift API 和过滤器语言

> 贡献者：[xixici](https://github.com/xixici)

Apache [Thrift](https://thrift.apache.org/) 是跨平台跨语言的开发框架。HBase 包含了 Thrift API 和过滤语言。Thrift API 依赖于客户端和服务器进程。

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

接下来，讨论 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\. 运算次序

1.  括号有着最高优先级

2.  然后是一元运算符 `SKIP` 和 `WHILE` ，优先级相同

3.  二元运算符 `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\. 比较运算符

以下比较运算符：

1.  LESS (<)

2.  LESS_OR_EQUAL (⇐)

3.  EQUAL (=)

4.  NOT_EQUAL (!=)

5.  GREATER_OR_EQUAL (>=)

6.  GREATER (>)

7.  NO_OP (no operation)

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

### 103.5\. 比较器

比较器可以如下任一种：

1.  _BinaryComparator_ - 按字典顺序比较特定字节数组，使用 Bytes.compareTo(byte[], byte[])

2.  _BinaryPrefixComparator_ -  按字典顺序比较特定字节数组，只比较字节数组长度.

3.  _RegexStringComparator_ - 使用给定正则表达式，比较特定字节组。在这种比较器中，只有 EQUAL 和 NOT_EQUAL 有效

4.  _SubStringComparator_ - 给定字符子串是否出现在特定字节组中。不区分大小写。在这种比较器中，只有 EQUAL 和 NOT_EQUAL 有效

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

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

1.  _BinaryComparator_ - binary 二进制

2.  _BinaryPrefixComparator_ - binaryprefix 二进制长度

3.  _RegexStringComparator_ - regexstring 正则表达式

4.  _SubStringComparator_ - substring 子字符串

  ComparatorValue 可以任意值

比较示例：

1.  `binary:abc` 匹配字典顺序大于"abc"

2.  `binaryprefix:abc` 匹配字典书序前 3 字符等于 "abc"

3.  `regexstring:ab*yz` 匹配以 ab 开头，已 yz 结尾的内容

4.  `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。