Filters
Filter query results on the server side by applying SingleColumnValueFilter or CompositeColumnValueFilter in the Tablestore PHP SDK.
Prerequisites
Filter types
Tablestore provides the following filter types:
-
SingleColumnValueFilter: Evaluates the value of a single attribute column against a condition.
-
CompositeColumnValueFilter: Combines multiple filter conditions with logical operators. Combine up to 32 filter conditions by using logical operators.
SingleColumnValueFilter
[
'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) by using a range query, and 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,
// Build a filter to return 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
$request['column_filter']['pass_if_missing'] = false; -
To evaluate all versions of the attribute column (return the row if any version meets the condition), set
$request['column_filter']['latest_version_only'] = false;
CompositeColumnValueFilter
Combine up to 32 filter conditions by using 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 CompositeColumnValueFilter 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.";
}