过滤器 Filter 可以在服务器端对读取的结果再进行一次过滤,根据 Filter 中的条件决定返回哪些行或者列。Filter 可以用于 GetRow、BatchGetRow 和 GetRange 接口的column_filter中。

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

需要注意的是,Filter 是对读取后的结果再进行一次过滤,所以 SingleColumnValueFilter 或者 CompositeColumnValueFilter 中的参考列必须在读取的结果内。如果用户指定了要读取的列,且其中不包含参考列,那么 Filter 无法获得这些参考列的值。 当某个参考列不存在时,SingleColumnValueFilter 的 passIfMissing 参数决定此时是否满足条件,即用户可以选择当参考列不存在时的行为。

格式

    'column_filter' => <ColumnFilter>

其中 SingleColumnValueFilter 结构如下

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

CompositeColumnValueFilter结构如下

    [
        'logical_operator' => <LogicalOperator>
        'sub_filters' => [
            <ColumnFilter>,
            <ColumnFilter>,
            <ColumnFilter>,
            // other conditions
        ]
    ]
格式说明
  • column_filter 过滤条件,
    • SingleColumnValueFilter 支持一列(可以是主键列)和一个常量比较。不支持两列相比较,也不支持两个常量相比较。
      • 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 比较类型
        • EQUAL 表示相等,用 ComparatorTypeConst::CONST_EQUAL 表示
        • NOT_EQUAL 表示不相等,用 ComparatorTypeConst::CONST_NOT_EQUAL 表示
        • GREATER_THAN 表示大于,用 ComparatorTypeConst::CONST_GREATER_THAN 表示
        • GREATER_EQUAL 表示大于等于,用 ComparatorTypeConst::CONST_GREATER_EQUAL 表示
        • LESS_THAN 表示小于,用 ComparatorTypeConst::CONST_LESS_THAN 表示
        • LESS_EQUAL 表示小于等于,用 ComparatorTypeConst::CONST_LESS_EQUAL 表示
      • pass_if_missing 由于OTS一行的属性列不固定,有可能存在有condition条件的列在该行不存在的情况,这时参数控制在这种情况下对该行的检查结果。
        • 如果设置为true,则若列在该行中不存在,该节点即认为true。
        • 如果设置为false,则若列在该行中不存在,该节点即认为false。
        • 默认值为true。
      • latest_version_only 是否只对最新版本有效。
        • 如果为true,则表示只检测最新版本的值是否满足条件;
        • 如果是false,则会检测所有版本的值是否满足条件,任意一个列值满足条件,该节点即认为true。
        • 默认值为true。
    • CompositeColumnValueFilter 一个树形结构,内节点为逻辑运算(logical_operator),叶节点为比较判断SingleColumnValueFilter
      • logical_operator 逻辑操作符,枚举类型
        • NOT 表示非,用 LogicalOperatorConst::CONST_NOT 表示。
        • AND 表示并,用 LogicalOperatorConst::CONST_AND 表示。
        • OR 表示或,用 LogicalOperatorConst::CONST_OR 表示。
      • sub_filters 递归下去, 可以继续是SingleColumnValueFilter 或 CompositeColumnValueFilter
        • 其中并和或可以挂载两个或更多子节点,非只能挂载一个子节点。

    示例 1

    构造 SingleColumnValueFilter。

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

    构造 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
                ]
            ]
        ];