--- title: "兼容 HBase 的 Filter - OceanBase 数据库 V4.3.5 | OceanBase 文档中心" description: 兼容 HBase 的 Filter OBKV-HBase 客户端实现了 Filter 的接口。本文介绍了 OBKV-HBase 对开源 HBase 过滤器（Filter）的兼容性。 Filter 兼容性说明及示例 columnPrefixFilter columnPrefixFilter 是一个列名前缀过滤器， 可以… --- 切换语言 - 中文站 - 简体中文 - International - English - 日本站 - 日本語 文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库KV 型 - V 4.3.5 LTS # 兼容 HBase 的 Filter 更新时间：2026-04-15 16:01:32 [编辑](https://github.com/oceanbase/oceanbase-kv/edit/V4.3.5/zh-CN/200.obkv-hbase/700.obkv-hbase-reference/200.obkv-hbase-filter-compatibility.md) OBKV-HBase 客户端实现了 [Filter](https://svn.apache.org/repos/asf/hbase/hbase.apache.org/trunk/0.94/apidocs/org/apache/hadoop/hbase/filter/Filter.html) 的接口。本文介绍了 OBKV-HBase 对开源 HBase 过滤器（Filter）的兼容性。 ## Filter 兼容性说明及示例 ### columnPrefixFilter columnPrefixFilter 是一个列名前缀过滤器， 可以返回所有以指定字符串作为列名前缀的列。需要用户指定过滤所使用的前缀字符串。 示例如下： 找到所有列名以 `abc` 为开头的数据。 ```java byte[] prefix = Bytes.toBytes("abc"); columnPrefixFilter f = new columnPrefixFilter(prefix); scan.setFilter(f); ``` ### columnPaginationFilter columnPaginationFilter 是一个用于限制返回列数的过滤器。 从指定的列开始，返回指定数量的列（最新 version 的 cell），用于列分页，需要设置偏移量（offset）或者指定列（columnOffset）与返回数量（limit）。 示例如下： 从 `q` 列开始，返回 3 列数据。 ```java byte[] col = Bytes.toBytes("q"); columnPaginationFilter f = new columnPaginationFilter(3, col); scan.setFilter(f); ``` ### firstKeyOnlyFilter firstKeyOnlyFilter 返回每行的第一个数据单元（Cell）。 示例如下： 返回每行第一个数据单元（Cell）。 ```java firstKeyOnlyFilter f = new firstKeyOnlyFilter(); scan.setFilter(f); ``` ### keyOnlyFilter keyOnlyFilter 返回除 value 以外的所有数据信息。 可选择指定一个参数或者不指定。默认不指定时仅返回每一行的 component，即不返回 value。可指定参数 lenAsVal，布尔值，为 true 时使用 value 的长度代替 value 返回。 示例如下： 使用 value 的长度代替 value 返回。 ```java keyOnlyFilter f = new keyOnlyFilter(true); scan.setFilter(f); ``` ### randomRowFilter randomRowFilter 是一个行过滤器，用于随机地选择一部分行数据。这个过滤器可以用来实现随机采样，它可以根据一定的概率来决定是否保留某一行。 示例如下： 使用 0.3 的概率随机过滤数据。 ```java randomRowFilter f = new randomRowFilter(0.3); scan.setFilter(f); ``` ### timestampsFilter timestampsFilter 是一个时间戳过滤器。可以根据给定的时间戳对数据进行过滤，保留匹配成功的数据。 它可指定两个参数，第一个是时间戳的 list，必选项，提供需要保留的数据的时间戳。第二个参数是 bool 值，可选参数，默认值为 false，表示是否可以使用 SEEK_NEXT_USING_HINT。 示例如下： 返回时间戳为 `3` 和 `4` 的数据。 ```java ArrayList timestamps = new ArrayList<>(); timestamps.add(new Long(3)); timestamps.add(new Long(4)); timestampsFilter filter = new timestampsFilter(timestamps); scan.setFilter(f); ``` ### DependentColumnFilter DependentColumnFilter 是一个依赖列过滤器，用于过滤掉包含特定值的列。 它需要至少两个参数：列族和列名。它会找到每行中对应的数据单元（Cell），并返回所有与该数据单元时间戳相同的键值对。 你还可以指定第三个参数 `dropDependentColumn`，默认为 `false`。如果你设置为 `true`，它将跳过指定的数据单元，只返回相同时间戳的其他键值对。 此外，你还可以选择指定第四个和第五个参数：`CompareOperator` 和 `ByteArrayComparable`，这样你可以对数据单元进行比较过滤。 示例如下： 返回所有列族为 `family_group`，列名为 `column1`，数据值为 `value2` 的数据单元，并返回所有与其时间戳相同的其他数据单元。 ```java DependentColumnFilter filter = new DependentColumnFilter( Bytes.toBytes("family_group"), Bytes.toBytes("column1"), false, CompareFilter.CompareOp.EQUAL, new BinaryComparator(toBytes("value2")) ); scan.setFilter(filter); ``` ### SingleColumnValueExcludeFilter SingleColumnValueExcludeFilter 是一个列值过滤器，用于过滤掉包含特定值的列。 示例如下： 准备测试数据集如下： ```sql RowKey: key1||||ColumnFamily: cf||||Column Qualifier: column1||||Value: value1||||Timestampsss: 1723797655011 RowKey: key1||||ColumnFamily: cf||||Column Qualifier: column2||||Value: value2||||Timestampsss: 1723797655270 RowKey: key2||||ColumnFamily: cf||||Column Qualifier: column2||||Value: value2||||Timestampsss: 1723797655404 RowKey: row1||||ColumnFamily: cf||||Column Qualifier: column1||||Value: v1||||Timestampsss: 1723537364927 RowKey: row2||||ColumnFamily: cf||||Column Qualifier: column1||||Value: ||||Timestampsss: 1723537384827 ``` 1. 设置 Filter 为 SingleColumnValueFilter： ```java SingleColumnValueFilter filter = new SingleColumnValueFilter( "cf".getBytes(), "column2".getBytes(), CompareFilter.CompareOp.EQUAL, new BinaryComparator(toBytes(value2)) ); scan.setFilter(filter); ``` 返回结果如下： ```java RowKey: key1||||ColumnFamily: cf||||Column Qualifier: column1||||Value: value1||||Timestampsss: 1723797632274 RowKey: key1||||ColumnFamily: cf||||Column Qualifier: column2||||Value: value2||||Timestampsss: 1723797632504 RowKey: key2||||ColumnFamily: cf||||Column Qualifier: column2||||Value: value2||||Timestampsss: 1723797632622 RowKey: row1||||ColumnFamily: cf||||Column Qualifier: column1||||Value: v1||||Timestampsss: 1723537364927 RowKey: row2||||ColumnFamily: cf||||Column Qualifier: column1||||Value: ||||Timestampsss: 1723537384827 ``` 结果符合预期。 2. 重新设置 Filter 为 SingleColumnValueExcludeFilter： ```java SingleColumnValueExcludeFilter filter = new SingleColumnValueExcludeFilter( "cf".getBytes(), "column2".getBytes(), CompareFilter.CompareOp.EQUAL, new BinaryComparator(toBytes(value2)) ); scan.setFilter(filter); ``` 返回结果如下： ```java RowKey: key1||||ColumnFamily: cf||||Column Qualifier: column1||||Value: value1||||Timestampsss: 1723797613418 RowKey: row1||||ColumnFamily: cf||||Column Qualifier: column1||||Value: v1||||Timestampsss: 1723537364927 RowKey: row2||||ColumnFamily: cf||||Column Qualifier: column1||||Value: ||||Timestampsss: 1723537384827 ``` 结果还是包括上面所有的行，但是剔除了符合指定值或者比较的列，符合预期。 ### ColumnRangeFilter ColumnRangeFilter 是一个列范围过滤器，只保留指定范围内的列。 参数需要指定区间的下界和上界，以及是否开闭。如果区间下界/上界为 `NULL` 或者空字符串，则表示为无穷（即没有区间上界/下界）。 示例如下： 返回列族为 `cf`，列名从 `column1` 到 `column2` 的数据。包含 `column1`，不包含 `column2`。 ```java byte[] startColumn = Bytes.toBytes("column1"); byte[] endColumn = Bytes.toBytes("column2"); Filter f = new ColumnRangeFilter(startColumn, true, endColumn, false); ``` ### MultipleColumnPrefixFilter MultipleColumnPrefixFilter 是一个多列前缀过滤器，用于筛选包含特定前缀的列。 它可以指定多个列名前缀，参数个数不固定。 示例如下： 匹配前缀为 `column1` 或者 `column2` 的列。 ```java byte[][] prefixes = new byte[][] {Bytes.toBytes("column1"), Bytes.toBytes("column2")}; Filter f = new MultipleColumnPrefixFilter(prefixes); ``` ### MultiRowRangeFilter MultiRowRangeFilter 是一个多行范围过滤器，用于筛选指定范围内的行。 `MultiRowRangeFilter` 的输入参数是一个包含多个 `RowRange` 对象的列表。每个 `RowRange` 对象定义了一个区间，包括区间的上界、下界，以及区间是否是开区间或闭区间。另外，用户也可以直接提供多个前缀作为参数，HBase 客户端会自动将这些前缀转换为 `RowRange` 对象进行存储。需要注意的是，`MultiRowRangeFilter` 至少需要一个 `RowRange` 对象作为参数。 示例如下： 返回 `row1` 到 `row2` 和 `row3` 到 `row4` 之间的数据，包括 `row1` 但不包括其他行。 ```java List ranges = new ArrayList(); ranges.add(new MultiRowRangeFilter.RowRange("row3", false, "row4", false)); ranges.add(new MultiRowRangeFilter.RowRange("row1", true, "row2", false)); MultiRowRangeFilter f = new MultiRowRangeFilter(ranges); ``` ### InclusiveStopFilter InclusiveStopFilter 是一个包含停止过滤器，用于返回到指定行为止的所有行。 示例如下： 返回到 `row1` 为止，前面所有的行。 ```java Filter f = new InclusiveStopFilter(Bytes.toBytes("row1")); ``` ### FirstKeyValueMatchingQualifiersFilter FirstKeyValueMatchingQualifiersFilter 是一个过滤器，用于匹配特定列名（qualifier）的数据单元。它会返回所有数据单元，直到找到第一个匹配指定列名的单元为止。用户可以指定多个列名作为匹配条件。 示例如下： 返回每一行数据，直到找到 `column0` 或 `column1` 为止。 ```java TreeSet set = new TreeSet<>(Bytes.BYTES_COMPARATOR); set.add(Bytes.toBytes("column0")); set.add(Bytes.toBytes("column1")); Filter f = new FirstKeyValueMatchingQualifiersFilter(set); ``` ### FamilyFilter FamilyFilter 是一个列族过滤器，用于过滤掉包含特定列族的数据单元。 FamilyFilter 根据列族名进行数据过滤。用户可以指定一个比较操作符（<, <=, =, >, >=, !=）和一个比较器（默认为二进制比较器），以便比较列族名。 示例如下： 使用 FamilyFilter 过滤掉列族名为 `cf1` 的数据。 ```java FamilyFilter f = new FamilyFilter(CompareOperator.NOT_EQUAL, new BinaryComparator(Bytes.toBytes("cf1"))); ``` ### FuzzyRowFilter FuzzyRowFilter 是一个模糊行过滤器，用于过滤掉包含特定行键的数据单元。 FuzzyRowFilter 是一种基于行键（Rowkey）的模糊匹配过滤器，你可以自定义一个或多个匹配规则 `(rowkey key, fuzzy info)` 来过滤行键。其中 `fuzzy info` 是一个和行键长度相同的字节数组，对于 `fuzzy info` 的每一个字节位： - 如果 `fuzzy info` 的某个字节位为 `0`，则对应位置的行键字节必须与给定的字节相同。 - 如果 `fuzzy info` 的某个字节位为 `1`，则对应位置的行键字节可以是任何值。 示例如下： 假设行键的格式为 `userId_actionId_year_month`，其中 `userId` 占 4 字节，`actionId` 占 2 字节，`year` 占 4 字节，`month` 占 2 字节。要查询在 1 月份执行了 `action "99"` 的用户，可以使用以下查询： ```java List> data = new ArrayList<>(); byte[] fuzzyKey = "????_99_????_01".getBytes(); byte[] fuzzyInfo = new byte[] {1, 1, 1, 1, 0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0}; data.add(new Pair(fuzzyKey, fuzzyInfo)); FuzzyRowFilter f = new FuzzyRowFilter(data); ``` ### ColumnValueFilter ColumnValueFilter 是一个列值过滤器，用于过滤掉包含特定值的列。 它对指定列的内容进行过滤，根据用户给定的比较类型和内容对数据单元进行过滤，返回符合条件的数据单元。参数需要指定过滤的列族，列名，比较类型，比较内容。 示例如下： 获取列族名为 `cf`，列名为 `column`，并且值为 `value` 的数据。 ```java ColumnValueFilter filter = new ColumnValueFilter( cf, column, CompareOperaor.EQUAL, Bytes.toBytes("value") ); scan.setFilter(filter); ``` 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线