Tablestore supports server-side data filtering based on specified conditions during queries. Use filters in the Python SDK to return only the rows that match your filter criteria.
Prerequisites
Before you begin, ensure that you have:
How filters work
Filters are evaluated on the server after Tablestore scans the rows that match your primary key range. Read capacity units (RCU) are consumed for every scanned row regardless of whether the row passes the filter. To minimize unnecessary RCU consumption, define a precise primary key range before applying a filter.
Tablestore provides two filter types:
SingleColumnCondition— filters rows based on a single attribute column value. Use this when you need to match one column against a fixed value.CompositeColumnCondition— combines multiple conditions with logical operators (AND, OR, NOT). Use this when your filter logic spans multiple columns or requires compound expressions. Supports up to 32 conditions.
SingleColumnCondition
Filters rows based on whether a single attribute column meets a comparison condition.
class SingleColumnCondition(ColumnCondition)Code example
The following example runs a range query for rows with a primary key in the [row1, row3) range and returns only the rows where the col1 attribute column equals val1.
try:
# Set the start primary key for the query.
inclusive_start_primary_key = [('id', 'row1')]
# Set the end primary key for the query. The end key is exclusive.
exclusive_end_primary_key = [('id', 'row3')]
# Create a filter with the condition col1 == "val1".
singleColumnCondition = SingleColumnCondition('col1', 'val1', ComparatorType.EQUAL)
# Call the get_range method to query data.
consumed, next_start_primary_key, row_list, next_token = client.get_range('test_table', Direction.FORWARD,
inclusive_start_primary_key,
exclusive_end_primary_key,
column_filter=singleColumnCondition)
# Process the results.
print('* Read CU Cost: %s' % consumed.read)
print('* Write CU Cost: %s' % consumed.write)
print('* Rows Data:')
for row in row_list:
print(row.primary_key, row.attribute_columns)
except Exception as e:
print("Range get failed with error: %s" % e)-
To exclude rows that do not contain the specified attribute column:
singleColumnCondition.pass_if_missing = False -
To evaluate all data versions and return the row if any version meets the condition:
singleColumnCondition.latest_version_only = False
CompositeColumnCondition
Combines multiple filter conditions using logical operators. Supports up to 32 conditions and allows nesting CompositeColumnCondition objects for complex expressions.
class CompositeColumnCondition(ColumnCondition)Code example
The following example runs a range query for rows with a primary key in the [row1, row3) range and applies a composite filter:
(col1 == "val1" OR col2 == "val2") AND col3 == "val3"
try:
# Set the start primary key for the query.
inclusive_start_primary_key = [('id', 'row1')]
# Set the end primary key for the query. The end key is exclusive.
exclusive_end_primary_key = [('id', 'row3')]
# Create the first single-column condition: col1 == "val1".
singleColumnCondition1 = SingleColumnCondition('col1', 'val1', ComparatorType.EQUAL)
# Create the second single-column condition: col2 == "val2".
singleColumnCondition2 = SingleColumnCondition('col2', 'val2', ComparatorType.EQUAL)
# Create the first composite condition: col1 == "val1" OR col2 == "val2".
compositeColumnCondition1 = CompositeColumnCondition(LogicalOperator.OR)
compositeColumnCondition1.add_sub_condition(singleColumnCondition1)
compositeColumnCondition1.add_sub_condition(singleColumnCondition2)
# Create the third single-column condition: col3 == "val3".
singleColumnCondition3 = SingleColumnCondition('col3', 'val3', ComparatorType.EQUAL)
# Create the final composite condition: (col1 == "val1" OR col2 == "val2") AND col3 == "val3".
compositeColumnCondition2 = CompositeColumnCondition(LogicalOperator.AND)
compositeColumnCondition2.add_sub_condition(compositeColumnCondition1)
compositeColumnCondition2.add_sub_condition(singleColumnCondition3)
# Call the get_range method to query data.
consumed, next_start_primary_key, row_list, next_token = client.get_range('test_table', Direction.FORWARD,
inclusive_start_primary_key,
exclusive_end_primary_key,
column_filter=compositeColumnCondition2)
# Process the results.
print('* Read CU Cost: %s' % consumed.read)
print('* Write CU Cost: %s' % consumed.write)
print('* Rows Data:')
for row in row_list:
print(row.primary_key, row.attribute_columns)
except Exception as e:
print("Range get failed with error: %s" % e)