兼容 HBase 的 Filter

更新时间：2026-07-23 19:56:22

编辑

OBKV-HBase 客户端实现了 Filter 的接口。本文介绍了 OBKV-HBase 对开源 HBase 过滤器（Filter）的兼容性。

Filter 兼容性说明及示例

columnPrefixFilter

columnPrefixFilter 是一个列名前缀过滤器，

可以返回所有以指定字符串作为列名前缀的列。需要用户指定过滤所使用的前缀字符串。

示例如下：

找到所有列名以 abc 为开头的数据。

byte[] prefix = Bytes.toBytes("abc");
columnPrefixFilter f = new columnPrefixFilter(prefix);
scan.setFilter(f);

columnPaginationFilter

columnPaginationFilter 是一个用于限制返回列数的过滤器。

从指定的列开始，返回指定数量的列（最新 version 的 cell），用于列分页，需要设置偏移量（offset）或者指定列（columnOffset）与返回数量（limit）。

示例如下：

从 q 列开始，返回 3 列数据。

byte[] col = Bytes.toBytes("q");
columnPaginationFilter f = new columnPaginationFilter(3, col);
scan.setFilter(f);

firstKeyOnlyFilter

firstKeyOnlyFilter 返回每行的第一个数据单元（Cell）。

示例如下：

返回每行第一个数据单元（Cell）。

firstKeyOnlyFilter f = new firstKeyOnlyFilter();
scan.setFilter(f);

keyOnlyFilter

keyOnlyFilter 返回除 value 以外的所有数据信息。

可选择指定一个参数或者不指定。默认不指定时仅返回每一行的 component，即不返回 value。可指定参数 lenAsVal，布尔值，为 true 时使用 value 的长度代替 value 返回。

示例如下：

使用 value 的长度代替 value 返回。

keyOnlyFilter f = new keyOnlyFilter(true);
scan.setFilter(f);

randomRowFilter

randomRowFilter 是一个行过滤器，用于随机地选择一部分行数据。这个过滤器可以用来实现随机采样，它可以根据一定的概率来决定是否保留某一行。

示例如下：

使用 0.3 的概率随机过滤数据。

randomRowFilter f = new randomRowFilter(0.3);
scan.setFilter(f);

timestampsFilter

timestampsFilter 是一个时间戳过滤器。可以根据给定的时间戳对数据进行过滤，保留匹配成功的数据。

它可指定两个参数，第一个是时间戳的 list，必选项，提供需要保留的数据的时间戳。第二个参数是 bool 值，可选参数，默认值为 false，表示是否可以使用 SEEK_NEXT_USING_HINT。

示例如下：

返回时间戳为 3 和 4 的数据。

ArrayList<Long> 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 的数据单元，并返回所有与其时间戳相同的其他数据单元。

DependentColumnFilter filter = new DependentColumnFilter(
    Bytes.toBytes("family_group"),
    Bytes.toBytes("column1"),
    false,
    CompareFilter.CompareOp.EQUAL,
    new BinaryComparator(toBytes("value2"))
    );
scan.setFilter(filter);

SingleColumnValueExcludeFilter

SingleColumnValueExcludeFilter 是一个列值过滤器，用于过滤掉包含特定值的列。

示例如下：

准备测试数据集如下：

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

设置 Filter 为 SingleColumnValueFilter：

SingleColumnValueFilter filter = new SingleColumnValueFilter(
"cf".getBytes(),
"column2".getBytes(), 
CompareFilter.CompareOp.EQUAL,
    new BinaryComparator(toBytes(value2))
    );
scan.setFilter(filter);

返回结果如下：

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

结果符合预期。

重新设置 Filter 为 SingleColumnValueExcludeFilter：

SingleColumnValueExcludeFilter filter = new SingleColumnValueExcludeFilter(
    "cf".getBytes(),
    "column2".getBytes(), 
    CompareFilter.CompareOp.EQUAL,
    new BinaryComparator(toBytes(value2))
    );
scan.setFilter(filter);

返回结果如下：

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。

byte[] startColumn = Bytes.toBytes("column1");
byte[] endColumn = Bytes.toBytes("column2");
Filter f = new ColumnRangeFilter(startColumn, true, endColumn, false);

MultipleColumnPrefixFilter

MultipleColumnPrefixFilter 是一个多列前缀过滤器，用于筛选包含特定前缀的列。

它可以指定多个列名前缀，参数个数不固定。

示例如下：

匹配前缀为 column1 或者 column2 的列。

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 但不包括其他行。

List<MultiRowRangeFilter.RowRange> ranges = new ArrayList<MultiRowRangeFilter.RowRange>();
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 为止，前面所有的行。

Filter f = new InclusiveStopFilter(Bytes.toBytes("row1"));

FirstKeyValueMatchingQualifiersFilter

FirstKeyValueMatchingQualifiersFilter 是一个过滤器，用于匹配特定列名（qualifier）的数据单元。它会返回所有数据单元，直到找到第一个匹配指定列名的单元为止。用户可以指定多个列名作为匹配条件。

示例如下：

返回每一行数据，直到找到 column0 或 column1 为止。

TreeSet<byte []> 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 的数据。

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" 的用户，可以使用以下查询：

List<Pair<byte[], byte[]>> 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<byte[], byte[]>(fuzzyKey, fuzzyInfo));
FuzzyRowFilter f = new FuzzyRowFilter(data);

ColumnValueFilter

ColumnValueFilter 是一个列值过滤器，用于过滤掉包含特定值的列。

它对指定列的内容进行过滤，根据用户给定的比较类型和内容对数据单元进行过滤，返回符合条件的数据单元。参数需要指定过滤的列族，列名，比较类型，比较内容。

示例如下：

获取列族名为 cf，列名为 column，并且值为 value 的数据。

ColumnValueFilter filter = new ColumnValueFilter(
  cf,
  column,
  CompareOperaor.EQUAL,
  Bytes.toBytes("value")
  );
scan.setFilter(filter);