Read a row - Tablestore SDK for Python - Tablestore - Alibaba Cloud Documentation Center

Use Tablestore SDK for Python to read a row by primary key and optionally specify attribute columns, data versions, or a filter.

Prerequisites

Install the Tablestore SDK for Python and initialize a client.

Function description

Call get_row to read a row.

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,
)

The following example reads the row whose primary key is ("device", 1) from example_table. Only the latest version of each attribute column is returned.

primary_key = [("partition", "device"), ("id", 1)]

consumed, return_row, next_token = client.get_row(
    "example_table",
    primary_key,
)
if return_row is not None:
    print(return_row.primary_key)
    print(return_row.attribute_columns)

Parameters

The get_row method contains the following parameters.

Name	Type	Description
table_name (required)	`str`	The name of the table.
primary_key (required)	`List[Tuple]`	The primary key. Specify all primary key columns. Their names, order, number, and types must match the primary key schema of the table.
columns_to_get (optional)	`List[str]`	The primary key or attribute columns to return. If this parameter is omitted, the entire row is returned. If the row contains none of the specified attribute columns, `return_row` is `None`.
column_filter (optional)	`ColumnCondition`	The filter. For more information, see Use filters. If you specify both `columns_to_get` and `column_filter`, columns are selected before the filter is applied.
max_version (optional)	`int`	The maximum number of versions to return for each attribute column. Default value: `1`. If more versions match, they are returned from newest to oldest. You must specify either `max_version` or `time_range`. To use `time_range`, set `max_version` to `None`.
time_range (optional)	`Tuple[int, int]`	The data version range in milliseconds. The start is inclusive, and the end is exclusive. Only data versions within this range are returned. This parameter and `max_version` are mutually exclusive.
start_column (optional)	`str`	The start attribute column for reading a wide row.
end_column (optional)	`str`	The end attribute column for reading a wide row.
token (optional)	`bytes`	The start position for the next page of a wide row. Use the `next_token` returned by the previous request.
transaction_id (optional)	`str`	The local transaction ID. Specify this parameter only for reads in a local transaction. For more information, see Use local transactions.

Response

get_row returns the following values.

Field	Type	Description
consumed	`CapacityUnit`	The read and write CUs consumed by the operation.
return_row	`Row`	The returned row. This value is `None` if the row does not exist, does not pass the filter, or contains none of the specified attribute columns.
next_token	`bytes`	The start position for the next page of a wide row. A value of `None` indicates that all attribute columns in the row have been read.

Examples

Specify attribute columns

The following example returns only the status and temperature attribute columns.

primary_key = [("partition", "device"), ("id", 1)]
columns_to_get = ["status", "temperature"]

consumed, return_row, next_token = client.get_row(
    "example_table",
    primary_key,
    columns_to_get=columns_to_get,
)

Specify a data version range

The following example returns all data versions written within the last day.

end_time = int(time.time() * 1000)
start_time = end_time - 86400 * 1000
primary_key = [("partition", "device"), ("id", 1)]

consumed, return_row, next_token = client.get_row(
    "example_table",
    primary_key,
    max_version=None,
    time_range=(start_time, end_time),
)

Filter the row

The following example returns the row only if the latest value of the status attribute column is online.

primary_key = [("partition", "device"), ("id", 1)]
column_filter = SingleColumnCondition(
    "status",
    "online",
    ComparatorType.EQUAL,
    pass_if_missing=False,
)

consumed, return_row, next_token = client.get_row(
    "example_table",
    primary_key,
    column_filter=column_filter,
)