Filter query results on the server side by applying SingleColumnValueFilter or CompositeColumnValueFilter in the Tablestore PHP SDK.
Prerequisites
Before you begin, ensure that you have:
How filters work
Filters run on the server after Tablestore reads the rows that match your primary key range, but before the results are returned to your application. Because the read happens first, filters do not reduce read capacity unit (CU) consumption — your application is charged for reading all rows in the range, regardless of how many rows the filter passes. Use filters to reduce network transfer and application-side processing, not to reduce read costs.
When a filter does not reduce the result set significantly, consider using a more selective primary key range or a secondary index instead.
Tablestore provides two filter types:
SingleColumnValueFilter: Evaluates a single attribute column against a condition.
CompositeColumnValueFilter: Combines up to 32 filter conditions with AND, OR, or NOT logical operators.
SingleColumnValueFilter
Use SingleColumnValueFilter to filter rows based on the value of one attribute column.
[
'column_name' => '<string>',
'value' => <ColumnValue>,
'comparator' => <ComparatorType>,
'pass_if_missing' => true || false,
'latest_version_only' => true || false
]Example
The following example reads rows with primary keys in the range [row1, row3) using getRange, then applies a filter to return only rows where col1 equals val1.
$request = array (
'table_name' => 'test_table',
// Set the start primary key for the range query.
'inclusive_start_primary_key' => array (
array('id', 'row1')
),
// Set the end primary key for the range query. The result does not include this key.
'exclusive_end_primary_key' => array (
array('id', 'row3')
),
// Read data in forward order.
'direction' => DirectionConst::CONST_FORWARD,
// Read the latest version of data.
'max_versions' => 1,
// Return only rows where col1 equals "val1".
'column_filter' => array (
'column_name' => 'col1',
'value' => 'val1',
'comparator' => ComparatorTypeConst::CONST_EQUAL
)
);
try {
// Call getRange to read rows.
$response = $client->getRange ($request);
// Process the response.
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.";
}-
To exclude rows that do not contain the specified attribute column, set
pass_if_missingtofalse:$request['column_filter']['pass_if_missing'] = false; -
To return a row if any version of the attribute column meets the condition (not just the latest), set
latest_version_onlytofalse:$request['column_filter']['latest_version_only'] = false;
CompositeColumnValueFilter
Use CompositeColumnValueFilter to combine up to 32 filter conditions with logical operators.
[
'logical_operator' => <LogicalOperator>
'sub_filters' => [
<ColumnFilter>,
<ColumnFilter>,
<ColumnFilter>,
// other conditions
]
]Example
The following example reads rows with primary keys in the range [row1, row3) and applies a composite filter with the condition (col1 = val1 OR col2 = val2) AND (col3 = val3).
$request = array (
'table_name' => 'test_table',
// Set the start primary key for the range query.
'inclusive_start_primary_key' => array (
array('id', 'row1')
),
// Set the end primary key for the range query. The result does not include this key.
'exclusive_end_primary_key' => array (
array('id', 'row3')
),
// Read data in forward order.
'direction' => DirectionConst::CONST_FORWARD,
// Read the latest version of data.
'max_versions' => 1
);
// Combine conditions: (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 {
// Call getRange to read rows.
$response = $client->getRange ($request);
// Process the response.
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.";
}