如何使用过滤器

过滤器 Filter 可以在服务端对读取的结果再进行一次过滤，根据 Filter 中的条件决定返回哪些行。由于只返回了符合条件的数据行，所以在大部分场景下，可以有效降低网络传输的数据量，减少响应时间。
表格存储 Filter 的过滤条件支持算术运算（=、!=、>、>=、<、<=）和逻辑运算（NOT、AND、OR），支持最多 10 个条件的组合，可以用于 GetRow、 BatchGetRow 和 GetRange 接口中。

使用说明


目前表格存储仅支持 SingleColumnValueFilter 和 CompositeColumnValueFilter，这两个 Filter 都是基于参考列的列值决定是否过滤某行。SingleColumnValueFilter 只判断某个参考列的列值，CompositeColumnValueFilter 会对多个参考列的列值判断结果进行逻辑组合，决定最终是否过滤。
API 文档参考： ColumnCondition。

• 
  构造 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 或者 CompositeColumnValueFilter 中的参考列必须在读取的结果内。如果用户指定了要读取的列，但其中不包含参考列，则 Filter 无法获得这些参考列的值。当某个参考列不存在时，SingleColumnValueFilter 的 passIfMissing 参数决定此时是否满足条件，即用户可以选择当参考列不存在时的行为。

使用场景示例


以物联网中的智能电表为例，智能电表按一定的频率（比如每隔 15 秒）将当前的电压、电流、度数等信息写入表格存储。在按天做分析的时候，我们需要拿到某一个电表当天是否出现过电压异常以及出现时的其他状态数据，来决定是否需要对某条线路进行检修。
按照目前的方案，使用 GetRange 读取一个电表一天内的所有的监控数据，共有 5760 条之多，然后再对这 5760 条信息进行过滤，拿到了最终的 10 个电压出现不稳定时的监控信息。
使用过滤器 Filter 只返回了实际需要的 10 条数据，大大降低了返回的数据量。而且，不需要再对结果进行初步的过滤处理，节省了开发代价。

费用计算


使用过滤器 Filter 之后，虽然有效降低了返回的数据量，但由于服务器端进行过滤计算是在数据返回给用户之前进行的，并没有降低磁盘 IO 次数，所以消耗的读 CU 与不使用过滤器的情况下相同，即使用过滤器与否不影响 CU 计算。
例如，使用 GetRange 读取到 100 条记录，共 200 KB 数据，共消耗了 50 个读 CU，在使用了过滤器之后，实际返回了 10 条数据，共 20 KB，但仍然会消耗 50 个读 CU。

特别说明


在 GetRow、BatchGetRow 和 GetRange 接口中使用过滤器除了不影响费用计算外，也不会改变使用接口的原生语义及限制项设定。
使用 GetRange 接口时，会受到一次返回数据的行数超过 5000 行或者返回数据的数据大小大于 4 MB 的限制，当在该次返回的 5000 行或者 4 MB 数据中没有满足 Filter 过滤条件的记录时，得到的 Response 中的 Rows 为空，但是 next_start_primary_key 可能不为空，此时需要使用 next_start_primary_key 继续读取数据，直到 next_start_primary_key 为空。详情请参见 GetRange 接口说明。