表格存储 PHP SDK 过滤器-表格存储 Tablestore(Tablestore)-阿里云帮助中心

表格存储支持在查询数据时使用过滤器在服务端按指定条件进行数据过滤，本文介绍如何在 PHP SDK 中使用过滤器。

前提条件

过滤器类型

表格存储的过滤器类型包括以下 2 种。

单属性列值过滤器（SingleColumnValueFilter）：判断单个属性列的值是否符合条件。
组合过滤器（CompositeColumnValueFilter）：将多个条件组合进行数据过滤。

单属性列值过滤器

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

参数说明

名称	类型	说明
comparator（必选）	ComparatorTypeConst	关系运算符，包括 CONST_EQUAL（等于）、CONST_NOT_EQUAL（不等于）、CONST_GREATER_THAN（大于）、CONST_GREATER_EQUAL（大于等于）、CONST_LESS_THAN（小于）、CONST_LESS_EQUAL（小于等于）。
column_name（必选）	string	判断的属性列名称。
value（必选）	STRING，INTEGER，BINARY，DOUBLE，BOOLEAN	判断的值。
pass_if_missing（可选）	bool	行数据不包含判断的属性列时，是否返回该行，默认值为 true，即返回该行数据。
latest_version_only（可选）	bool	是否只判断查询结果中最新的数据版本，默认值为 true，即当参考的属性列存在多个数据版本时，只判断最新的数据版本是否符合过滤条件。

示例代码

以下示例代码以范围查询为例查询主键值为 [row1, row3) 的行数据，并在查询后进行过滤，返回 col1 属性列的值等于 val1 的行数据。

$request = array (
    'table_name' => 'test_table',
    // 设置查询起始主键
    'inclusive_start_primary_key' => array (
        array('id', 'row1')
    ),
    // 设置查询结束主键（返回结果不包含结束主键）
    'exclusive_end_primary_key'  => array (
        array('id', 'row3')
    ),
    // 设置正向读取数据
    'direction' => DirectionConst::CONST_FORWARD,
    // 设置查询版本
    'max_versions' => 1,
    // 构造过滤器，条件为 col1 == "val1"
    'column_filter' => array (
        'column_name' => 'col1',
        'value' => 'val1',
        'comparator' => ComparatorTypeConst::CONST_EQUAL
    )
);

try {
    // 调用 getRange 方法读取行数据
    $response = $client->getRange ($request);

    // 返回结果处理
    echo "* Read CU Cost: " . $response['consumed']['capacity_unit']['read'] . "\n";
    echo "* Write CU Cost: " . $response['consumed']['capacity_unit']['write'] . "\n";
    echo "* Row Data: " . "\n";
    foreach ($response['rows'] as $row) {
        echo json_encode($row) . "\n";
    }
} catch (Exception $e){
    echo "Get Range failed.";
}

设置行数据不包含判断的属性列时，不返回该行。
```
$request['column_filter']['pass_if_missing'] = false;
```
设置判断查询结果中所有版本的数据，此时只要有一个版本的数据符合条件，即返回该行数据。
```
$request['column_filter']['latest_version_only'] = false;
```

组合过滤器

最多支持 32 个条件的组合。

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

参数说明

名称	类型	说明
logical_operator（必选）	LogicalOperatorConst	逻辑运算符，包括 CONST_NOT（非）、CONST_AND（与）、CONST_OR（或）。
sub_filters（必选）	array	参与逻辑运算的过滤器，包括单属性列值过滤器和组合过滤器。

示例代码

以下示例代码以范围查询为例查询主键值为 [row1, row3) 的行数据，并使用组合过滤器进行数据过滤。

$request = array (
    'table_name' => 'test_table',
    // 设置查询起始主键
    'inclusive_start_primary_key' => array (
        array('id', 'row1')
    ),
    // 设置查询结束主键（返回结果不包含结束主键）
    'exclusive_end_primary_key'  => array (
        array('id', 'row3')
    ),
    // 设置正向读取数据
    'direction' => DirectionConst::CONST_FORWARD,
    // 设置查询版本
    'max_versions' => 1
);

// 组合条件，判断条件为 (col1 = val1 or col2 = val2) and (col3 = val3)
$request['column_filter'] = array(
    'logical_operator' => LogicalOperatorConst::CONST_AND,
    'sub_filters' => array(
        array(
            'logical_operator' => LogicalOperatorConst::CONST_OR,
            'sub_filters' => array(
                array(
                    'comparator' => ComparatorTypeConst::CONST_EQUAL,
                    'column_name' => 'col1',
                    'value' => 'val1'
                ),
                array(
                    'comparator' => ComparatorTypeConst::CONST_EQUAL,
                    'column_name' => 'col2',
                    'value' => 'val2'
                )
            )
        ),
        array(
            'comparator' => ComparatorTypeConst::CONST_EQUAL,
            'column_name' => 'col3',
            'value' => 'val3'
        )
    )
);

try {
    // 调用 getRange 方法读取行数据
    $response = $client->getRange ($request);

    // 返回结果处理
    echo "* Read CU Cost: " . $response['consumed']['capacity_unit']['read'] . "\n";
    echo "* Write CU Cost: " . $response['consumed']['capacity_unit']['write'] . "\n";
    echo "* Row Data: " . "\n";
    foreach ($response['rows'] as $row) {
        echo json_encode($row) . "\n";
    }
} catch (Exception $e){
    echo "Get Range failed.";
}

前提条件

过滤器类型

单属性列值过滤器

示例代码

组合过滤器

示例代码

相关文档