All Products
Search

This Product

    Tablestore:Read a single row of data

    Document Center

    Tablestore:Read a single row of data

    Last Updated:Mar 31, 2026

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

    Usage notes

    When you read data, you must provide the complete primary key value, including the value of any auto-increment primary key column.

    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, which includes the names and values of primary key columns.

    • The data type of a primary key column can be STRING, INTEGER, or BINARY.

    • The number and data types of the primary key columns must match the table's 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 the number of matching data versions exceeds this value, the method returns that number of the most recent versions in descending order of timestamp.

    time_range (Optional)

    Tuple

    The version range of the data.

    • You must specify either the max_version or time_range parameter.

    • Each attribute column in a Tablestore data table can have multiple data versions. If you specify a version range, the method returns only data within that range.

    columns_to_get (Optional)

    List[str]

    A list of data columns to read. This list can include both primary key columns and attribute columns.

    • If you omit this parameter, the method returns the entire row.

    • If the row does not contain any of the specified columns, the returned row object includes the primary key but no attribute columns.

    column_filter (Optional)

    ColumnCondition

    The filter condition. For more information, see Filter.

    • If you specify both columns_to_get and column_filter, the system first retrieves the columns specified in columns_to_get and then applies the column_filter to the results.

    transaction_id (Optional)

    str

    The local transaction ID, which uniquely identifies a local transaction. For more information, see Local transactions.

    Examples

    The following example reads a single row where the primary key value is 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