全部产品
Search
文档中心

表格存储:过滤器

更新时间:Jul 23, 2024

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

前提条件

使用方法

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

过滤器目前包括SingleColumnValueFilter和CompositeColumnValueFilter。

  • SingleColumnValueFilter:只判断某个参考列的列值。

  • 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时返回该行数据。

$request = [
    'table_name' => 'MyTable',
    'primary_key' => [ //设置主键。
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'max_versions' => 1,                     //设置读取最新版本。
    'columns_to_get' => ['col0'],             //设置读取的列。
    
    //设置过滤器,当Col0的值为0时,返回该行。
    'column_filter' => [
        'column_name' => 'col0',
        'value' => 0,
        'comparator' => ComparatorTypeConst::CONST_EQUAL,
        'pass_if_missing' => false,                         //如果不存在Col0列,也不返回该行。
        'latest_version_only' => true                      //只判断最新版本。
    ]
];
$response = $otsClient->getRow ($request); 

使用CompositeColumnValueFilter过滤数据

以下示例用于读取数据表中的一行数据,当Col0列值等于0且Col1小于100时返回该行数据。

    //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
            ]
        ]
    ];  
                    

相关文档

  • 当某些应用需要使用不同属性作为查询条件来执行数据查询时,您可以通过将这些属性作为二级索引的主键列实现按照属性快速查询数据的需求。更多信息,请参见二级索引

  • 当日常业务中有非主键列查询、多列组合查询、模糊查询等多维查询需求以及求最值、统计行数、数据分组等数据分析需求时,您可以将这些属性作为多元索引中的字段并使用多元索引查询与分析数据。 更多信息,请参见多元索引

  • 您还可以通过SQL查询与分析表中数据。更多信息,请参见查询数据