过滤器

相关接口

过滤器类型

API 文档参考：CompositeColumnValueFilter ， SingleColumnValueFilter。

Java 示例

• 构造 SingleColumnValueFilter

    // 设置过滤器, 当 Col0 的值为 0 时返回该行。
    SingleColumnValueFilter singleColumnValueFilter = new SingleColumnValueFilter("Col0",
            SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
    // 如果不存在 Col0 这一列, 也不返回。
    singleColumnValueFilter.setPassIfMissing(false);
  					

• 构造 CompositeColumnValueFilter

    // composite1 条件为 (Col0 == 0) AND (Col1 > 100)
    CompositeColumnValueFilter composite1 = new CompositeColumnValueFilter(CompositeColumnValueFilter.LogicOperator.AND);
    SingleColumnValueFilter single1 = new SingleColumnValueFilter("Col0",
            SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
    SingleColumnValueFilter single2 = new SingleColumnValueFilter("Col1",
            SingleColumnValueFilter.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100));
    composite1.addFilter(single1);
    composite1.addFilter(single2);
  
    // composite2 条件为 ( (Col0 == 0) AND (Col1 > 100) ) OR (Col2 <= 10)
    CompositeColumnValueFilter composite2 = new CompositeColumnValueFilter(CompositeColumnValueFilter.LogicOperator.OR);
    SingleColumnValueFilter single3 = new SingleColumnValueFilter("Col2",
            SingleColumnValueFilter.CompareOperator.LESS_EQUAL, ColumnValue.fromLong(10));
    composite2.addFilter(composite1);
    composite2.addFilter(single3);
  					

过滤器是对读取后的结果再进行一次过滤，所以 Filter 中的参考列必须在读取的结果内。如果指定了要读取的列，但其中不包含参考列，则过滤器无法获得这些参考列的值。

当某个参考列不存在时，SingleColumnValueFilter 的 passIfMissing 参数决定此时是否满足条件，即您可以选择当参考列不存在时的行为。

使用场景

以物联网中的智能电表为例，智能电表按一定的频率（例如每隔 15 秒）将当前的电压、电流、度数等信息写入表格存储。在按天做分析的时候，需要拿到某一个电表当天是否出现过电压异常以及出现时的其他状态数据，来决定是否需要对某条线路进行检修。

按照目前的方案，使用 GetRange 读取一个电表一天内的所有的监控数据，共有 5760 条，然后再对这 5760 条信息进行过滤，拿到了最终的 10 个电压出现不稳定时的监控信息。

使用过滤器 Filter 只返回了实际需要的 10 条数据，有效降低了返回的数据量。而且不需要再对结果进行初步的过滤处理，节省了开发成本。

费用计算

使用过滤器之后，虽然有效降低了返回的数据量，但由于服务器端进行过滤计算是在数据返回给用户之前进行的，并没有降低磁盘 IO 次数，所以消耗的读 CU 与不使用过滤器的情况下相同，即使用过滤器与否不影响 CU 计算。

例如，使用 GetRange 读取到 100 条记录，共 200KB 数据，共消耗了 50 个读 CU，在使用了过滤器之后，实际返回了 10 条数据，共 20KB，但仍然会消耗 50 个读 CU。

特别说明

在 GetRow、BatchGetRow 和 GetRange 接口中使用过滤器除了不影响费用计算外，也不会改变使用接口的原生语义及限制项设定。

使用 GetRange 接口时，会受到一次返回数据的行数超过 5000 行或者返回数据的数据大小大于 4MB 的限制，当在该次返回的 5000 行或者 4MB 数据中没有满足 Filter 过滤条件的记录时，得到的 Response 中的 Rows 为空，但是 next_start_primary_key 可能不为空，此时需要使用 next_start_primary_key 继续读取数据，直到 next_start_primary_key 为空。详情请参见 GetRange 接口说明。