All Products
Search

This Product

    Tablestore:Read a single row of data

    Document Center

    Tablestore:Read a single row of data

    Last Updated:Jun 04, 2026

    Use the Python SDK to read a single row of data from a Tablestore data table.

    Usage notes

    Provide the complete primary key, including auto-increment primary key column values.

    Prerequisites

    Initialize Tablestore Client

    Method

    def get_row(self, table_name, primary_key, columns_to_get=None,
            column_filter=None, max_version=1, time_range=None,
            start_column=None, end_column=None, token=None,
            transaction_id=None):

    Parameters

    Parameter

    Type

    Description

    table_name (Required)

    str

    The name of the data table.

    primary_key (Required)

    List[Tuple]

    The primary key. Includes names and values of all primary key columns.

    • Supported data types: STRING, INTEGER, and BINARY.

    • The column count and data types must match the table schema.

    max_version (Optional)

    int

    The maximum number of versions to return. Default value: 1.

    • You must specify either the max_version or time_range parameter.

    • If more versions match, only the most recent versions up to this limit are returned, ordered by descending timestamp.

    time_range (Optional)

    Tuple

    The version range to query.

    • You must specify either the max_version or time_range parameter.

    • Attribute columns can have multiple versions. Only versions within the specified range are returned.

    columns_to_get (Optional)

    List[str]

    Columns to read. Can include both primary key and attribute columns.

    • If omitted, all columns are returned.

    • If the row contains none of the specified columns, the response includes only the primary key.

    column_filter (Optional)

    ColumnCondition

    The filter condition. Filter.

    • When both columns_to_get and column_filter are specified, the system retrieves the specified columns first, then applies the filter.

    transaction_id (Optional)

    str

    The ID of a local transaction. Local transactions.

    Examples

    Read a row with primary key value row1:

    try:
    # Construct the primary key.
    primary_key = [('id', 'row1')]

    # Call the get_row method to read the row data.
    consumed, return_row, next_token = client.get_row('test_table', primary_key)
    print('Read CU Cost: %s' % consumed.read)
    print('Write CU Cost: %s' % consumed.write)
    print('Row Data: %s %s' % (return_row.primary_key, return_row.attribute_columns))
except Exception as e:
    print("Get row failed with error: %s" % e)

    • To return only data within a specific version range, specify the time_range parameter.

      # Set the version range for the query to the last 24 hours.
time_range = (int(time.time() * 1000 - 86400 * 1000), int(time.time() * 1000))

# Call the get_row method to read the row data.
consumed, return_row, next_token = client.get_row('test_table', primary_key, time_range=time_range)

    • To retrieve specific attribute columns, specify the columns_to_get parameter.

      columns_to_get = ['col2']

# Call the get_row method to read the row data.
consumed, return_row, next_token = client.get_row('test_table', primary_key, columns_to_get=columns_to_get)

    References