# 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。