Table Store Python SDK 範圍讀取資料 - Tablestore

使用 Python SDK 按主鍵範圍讀取連續多行資料，並按需設定讀取方向、分頁、資料版本和過濾條件。

前提條件

功能說明

調用 get_range 方法按主鍵範圍讀取資料。返回範圍包含起始主鍵，不包含結束主鍵。

def get_range(
    self,
    table_name,
    direction,
    inclusive_start_primary_key,
    exclusive_end_primary_key,
    columns_to_get=None,
    limit=None,
    column_filter=None,
    max_version=1,
    time_range=None,
    start_column=None,
    end_column=None,
    token=None,
    transaction_id=None,
)

以下樣本正向讀取 example_table 中 device 分區內的所有行，僅返回每個屬性列的最新版本。

start_primary_key = [("partition", "device"), ("id", INF_MIN)]
end_primary_key = [("partition", "device"), ("id", INF_MAX)]

consumed, next_start_primary_key, rows, next_token = client.get_range(
    "example_table",
    Direction.FORWARD,
    start_primary_key,
    end_primary_key,
)
for row in rows:
    print(row.primary_key, row.attribute_columns)

說明

單次範圍讀取最多返回 5000 行或 4 MB 資料。超出限制時，使用響應中的 next_start_primary_key 繼續讀取。

參數說明

get_range 方法包含以下參數。

名稱	類型	說明
table_name（必選）	`str`	資料表名稱。
direction（必選）	`Direction`	讀取方向。`FORWARD` 表示正向讀取；`BACKWARD` 表示反向讀取。
inclusive_start_primary_key（必選）	`List[Tuple]`	起始主鍵，返回結果包含該主鍵。正向讀取時必須小於結束主鍵，反向讀取時必須大於結束主鍵。主鍵結構必須與資料表一致。
exclusive_end_primary_key（必選）	`List[Tuple]`	結束主鍵，返回結果不包含該主鍵。主鍵結構必須與資料表一致。
columns_to_get（可選）	`List[str]`	要返回的主鍵列或屬性列名稱。不設定時返回整行。
limit（可選）	`int`	單次請求最多返回的行數，必須大於 `0`。達到該值時，使用 `next_start_primary_key` 繼續讀取。
column_filter（可選）	`ColumnCondition`	過濾條件。有關配置方法，請參見過濾器。
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_range 返回以下值。

欄位	類型	說明
consumed	`CapacityUnit`	本次操作消耗的讀寫 CU。
next_start_primary_key	`List[Tuple]`	下一頁的起始主鍵。返回 `None` 表示主鍵範圍內的行已全部讀取。
rows	`List[Row]`	合格行資料。
next_token	`bytes`	寬行分頁讀取的下一頁起始位置。返回 `None` 表示當前行的屬性列已全部讀取。

情境樣本

分頁迭代讀取

以下樣本迴圈使用 next_start_primary_key，直到讀取完指定主鍵範圍內的所有行。

start_primary_key = [("partition", "device"), ("id", INF_MIN)]
end_primary_key = [("partition", "device"), ("id", INF_MAX)]

while start_primary_key:
    consumed, start_primary_key, rows, next_token = client.get_range(
        "example_table",
        Direction.FORWARD,
        start_primary_key,
        end_primary_key,
        limit=100,
    )

    for row in rows:
        print(row.primary_key, row.attribute_columns)

反向讀取

反向讀取時，起始主鍵必須大於結束主鍵。

start_primary_key = [("partition", "device"), ("id", INF_MAX)]
end_primary_key = [("partition", "device"), ("id", INF_MIN)]

consumed, next_start_primary_key, rows, next_token = client.get_range(
    "example_table",
    Direction.BACKWARD,
    start_primary_key,
    end_primary_key,
)

條件過濾讀取

以下樣本只返回 status 屬性列的最新值為 online 的行。

column_filter = SingleColumnCondition(
    "status",
    "online",
    ComparatorType.EQUAL,
    pass_if_missing=False,
)

consumed, next_start_primary_key, rows, next_token = client.get_range(
    "example_table",
    Direction.FORWARD,
    start_primary_key,
    end_primary_key,
    column_filter=column_filter,
)