Table Store Python SDK 讀取單行資料 - Tablestore

使用 Python SDK 按主鍵讀取單行資料，並按需指定屬性列、資料版本範圍和過濾條件。

前提條件

功能說明

調用 get_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,
)

以下樣本讀取 example_table 中主鍵為 ("device", 1) 的一行資料，僅返回每個屬性列的最新版本。

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)

參數說明

get_row 方法包含以下參數。

名稱	類型	說明
table_name（必選）	`str`	資料表名稱。
primary_key（必選）	`List[Tuple]`	主鍵資訊。必須包含全部主鍵列，且主鍵列的名稱、順序、數量和類型與資料表的主鍵結構一致。
columns_to_get（可選）	`List[str]`	要返回的主鍵列或屬性列名稱。不設定時返回整行；設定後，如果目標行不包含任何指定的屬性列，則 `return_row` 為 `None`。
column_filter（可選）	`ColumnCondition`	過濾條件。有關配置方法，請參見過濾器。同時設定 `columns_to_get` 和 `column_filter` 時，先選擇要返回的列，再按條件過濾。
max_version（可選）	`int`	每個屬性列最多返回的版本數，預設值為 `1`。如果合格版本數超過該值，按從新到舊的順序返回。`max_version` 和 `time_range` 必須設定其中一個；設定 `time_range` 時，將 `max_version` 設定為 `None`。
time_range（可選）	`Tuple[int, int]`	資料版本範圍，單位為毫秒，左閉右開。僅返回版本號碼處於該範圍內的資料。與 `max_version` 二選一。
start_column（可選）	`str`	寬行讀取的起始屬性列名稱。
end_column（可選）	`str`	寬行讀取的結束屬性列名稱。
token（可選）	`bytes`	寬行分頁讀取的起始位置。值來自上一次請求返回的 `next_token`。
transaction_id（可選）	`str`	局部事務 ID。僅在局部事務內讀取資料時設定。有關使用方法，請參見局部事務。

傳回值

get_row 返回以下值。

欄位	類型	說明
consumed	`CapacityUnit`	本次操作消耗的讀寫 CU。
return_row	`Row`	返回的行資料。目標行不存在、未通過過濾條件或不包含任何指定的屬性列時為 `None`。
next_token	`bytes`	寬行分頁讀取的下一頁起始位置。返回 `None` 表示當前行的屬性列已全部讀取。

情境樣本

指定讀取的屬性列

以下樣本只返回 status 和 temperature 屬性列。

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

指定資料版本範圍

以下樣本返回過去一天內寫入的所有版本資料。

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

條件過濾讀取

以下樣本僅在 status 屬性列的最新值為 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,
)