All Products
Search

This Product

    Tablestore:Filter

    Document Center

    Tablestore:Filter

    Last Updated:Mar 31, 2026

    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

    Initialize a Tablestore client

    Filter types

    Tablestore provides the following two types of filters:

    • SingleColumnCondition: Filters rows based on whether a single attribute column meets a specified condition.

    • CompositeColumnCondition: Combines multiple filter conditions to perform complex filtering.

    Single-column condition

    class SingleColumnCondition(ColumnCondition)

    Parameters

    Parameter

    Type

    Description

    comparator (Required)

    ComparatorType

    The relational operator. Supported operators include EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_EQUAL, LESS_THAN, and LESS_EQUAL.

    column_name (Required)

    str

    The name of the attribute column to evaluate.

    column_value (Required)

    str, int, bytes, float, bool

    The value to compare against.

    pass_if_missing (Optional)

    bool

    Specifies whether to return a row that lacks the specified attribute column. Defaults to True, meaning the row is returned.

    latest_version_only (Optional)

    bool

    Specifies whether to evaluate only the latest version of the attribute column. Defaults to True. If True, the condition is checked only against the latest version, even if multiple versions of the column exist.

    Code example

    The following example performs a range query for rows with a primary key in the [row1, row3) range and applies a filter. Only rows where the col1 attribute column has a value of val1 are returned.

    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 prevent returning rows that do not contain the specified attribute column:

      singleColumnCondition.pass_if_missing = False

    • To evaluate all data versions in the query result and return the row if any version meets the condition:

      singleColumnCondition.latest_version_only = False

    Composite column condition

    A composite filter supports up to 32 conditions.

    class CompositeColumnCondition(ColumnCondition)

    Parameters

    Parameter

    Type

    Description

    combinator (Required)

    LogicalOperator

    The logical operator. Supported operators include NOT, AND, and OR.

    sub_conditions (Required)

    List[ColumnCondition]

    A list of filters to be combined. The list can contain SingleColumnCondition and CompositeColumnCondition objects.

    Code example

    The following example performs a range query for rows with a primary key in the [row1, row3) range and applies a composite filter to the results.

    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)

    References