过滤器 - 表格存储

在服务端对读取结果再进行一次过滤，根据过滤器（Filter）中的条件决定返回的行。使用过滤器后，只返回符合条件的数据行。

前提条件

已初始化Client，详情请参见初始化。
已创建数据表并写入数据。

使用方法

在通过GetRow、BatchGetRow或GetRange接口查询数据时，可以使用过滤器只返回符合条件的数据行。

过滤器目前包括SingleColumnValueFilter、SingleColumnValueRegexFilter和CompositeColumnValueFilter。

SingleColumnValueFilter：只判断某个参考列的列值。
SingleColumnValueRegexFilter：支持对类型为String的列值，使用正则表达式进行子字符串匹配，然后根据实际将匹配到的子字符串转换为String、Integer或者Double类型，再对子值使用过滤器进行过滤。
CompositeColumnValueFilter：根据多个参考列的列值的判断结果进行逻辑组合，决定是否过滤某行。

说明关于过滤器的更多信息，请参见功能介绍中的过滤器。

限制

过滤器的条件支持算术运算（=、!=、>、>=、<、<=）和逻辑运算（NOT、AND、OR），最多支持10个条件的组合。
过滤器中的参考列必须在读取的结果内。如果指定的要读取的列中不包含参考列，则过滤器无法获取参考列的值。
在GetRow、BatchGetRow和GetRange接口中使用过滤器不会改变接口的原生语义和限制项。
使用GetRange接口时，会受到一次扫描数据的行数不能超过5000行或者扫描数据的数据大小不能大于4 MB的限制。
当在该次扫描的5000行或者4 MB数据中没有满足过滤器条件的数据时，得到的Response中的Rows为空，但是next_start_primary_key可能不为空，此时需要使用next_start_primary_key继续读取数据，直到next_start_primary_key为空。

参数

过滤器可以用于GetRow、BatchGetRow和GetRange接口的column_filter中。

    'column_filter' => <ColumnFilter>

SingleColumnValueFilter结构

SingleColumnValueFilter支持一列（可以是主键列）和一个常量比较。不支持两列或者两个常量相比较。

    [
        'column_name' => '<string>',
        'value' => <ColumnValue>,
        'comparator' => <ComparatorType>
        'pass_if_missing' => true || false
        'latest_version_only' => true || false
    ]

CompositeColumnValueFilter结构

CompositeColumnValueFilter是一个树形结构，内节点为逻辑运算（logical_operator），叶节点为SingleColumnValueFilter。

    [
        'logical_operator' => <LogicalOperator>
        'sub_filters' => [
            <ColumnFilter>,
            <ColumnFilter>,
            <ColumnFilter>,
            // other conditions
        ]
    ]


参数	说明
column_name	过滤器中参考列的名称。
value	过滤器中参考列的对比值。格式为[Value, Type]。Type可以是INTEGER、STRING（UTF-8编码字符串）、BINARY、BOOLEAN、DOUBLE五种，分别用ColumnTypeConst::CONST_INTEGER、ColumnTypeConst::CONST_STRING、ColumnTypeConst::CONST_BINARY、ColumnTypeConst::CONST_BOOLEAN、ColumnTypeConst::CONST_DOUBLE表示，其中BINARY不可省略，其他类型均可省略。当Type不是BINARY时，可以简写为Value。
comparator	过滤器中的算术运算符，类型详情请参见ComparatorType。算术运算符包括EQUAL（=）、NOT_EQUAL（!=）、GREATER_THAN（>）、GREATER_EQUAL（>=）、LESS_THAN（<）和LESS_EQUAL（<=），分别用ComparatorTypeConst::CONST_EQUAL、ComparatorTypeConst::CONST_NOT_EQUAL、ComparatorTypeConst::CONST_GREATER_THAN、ComparatorTypeConst::CONST_GREATER_EQUAL、ComparatorTypeConst::CONST_LESS_THAN、ComparatorTypeConst::CONST_LESS_EQUAL表示。
logical_operator	过滤器中的逻辑运算符，类型详情请参见LogicalOperator。逻辑运算符包括NOT、AND和OR，分别用LogicalOperatorConst::CONST_NOT、LogicalOperatorConst::CONST_AND、LogicalOperatorConst::CONST_OR表示。
pass_if_missing	当参考列在某行中不存在时，是否返回该行。类型为bool值，默认值为true，表示如果参考列在某行中不存在，则返回该行。当pass_if_missing设置为false时，如果参考列在某行中不存在，则不返回该行。
latest_version_only	当参考列存在多个版本的数据时，是否只使用最新版本的值做比较。类型为bool值，默认值为true，表示如果参考列存在多个版本的数据时，则只使用该列最新版本的值进行比较。当latest_version_only设置为false时，如果参考列存在多个版本的数据时，则会使用该列的所有版本的值进行比较，此时只要有一个版本的值满足条件，就返回该行。
sub_filters	子节点可以是SingleColumnValueFilter或CompositeColumnValueFilter。内节点的逻辑运算符不同可以挂载的子节点个数不同。当内节点的逻辑运算符为NOT时，只能挂载一个子节点。当内节点的逻辑运算符为AND或OR时，可以挂载多个子节点。

示例

构造SingleColumnValueFilter。

    //设置过滤器，当Col0的值为0时，返回该行。
    $column_filter = [
        'column_name' => 'Col0',
        'value' => 0,
        'comparator' => ComparatorTypeConst::CONST_EQUAL 
        'pass_if_missing' => false                         //如果不存在Col0列，也不返回该行。
        'latest_version_only' => true                      //只判断最新版本。
    ];

构造CompositeColumnValueFilter。

    //composite1的条件为(Col0 == 0) AND (Col1 > 100)。
    $composite1 = [
        'logical_operator' => LogicalOperatorConst::CONST_AND,
        'sub_filters' => [
            [
                'column_name' => 'Col0',
                'value' => 0,
                'comparator' => ComparatorTypeConst::CONST_EQUAL
            ],
            [
                'column_name' => 'Col1',
                'value' => 100,
                'comparator' => ComparatorTypeConst::CONST_GREATER_THAN
            ]
        ]
    ];
    //composite2的条件为( (Col0 == 0) AND (Col1 > 100) ) OR (Col2 <= 10)。
    $composite2 = [
        'logical_operator' => LogicalOperatorConst::CONST_OR,
        'sub_filters' => [
            $composite1,
            [
                'column_name' => 'Col2',
                'value' => 10,
                'comparator' => ComparatorTypeConst::CONST_LESS_EQUAL
            ]
        ]
    ];