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

前提條件

安裝Tablestore Go SDK並初始化用戶端。

功能說明

調用 GetRange 讀取起始主鍵和結束主鍵之間的資料。結果包含起始主鍵對應的行，不包含結束主鍵對應的行。單次調用最多返回 5000 行或 4 MB 資料，超出限制時通過返回的下一起始主鍵繼續讀取。

func (tableStoreClient *TableStoreClient) GetRange(request *GetRangeRequest) (*GetRangeResponse, error)

以下樣本正向讀取 example_table 中 row1 之後的最多 100 行資料。

startKey := &tablestore.PrimaryKey{}
startKey.AddPrimaryKeyColumn("id", "row1")
endKey := &tablestore.PrimaryKey{}
endKey.AddPrimaryKeyColumnWithMaxValue("id")

request := &tablestore.GetRangeRequest{
    RangeRowQueryCriteria: &tablestore.RangeRowQueryCriteria{
        TableName:       "example_table",
        StartPrimaryKey: startKey,
        EndPrimaryKey:   endKey,
        Direction:       tablestore.FORWARD,
        MaxVersion:      1,
        Limit:           100,
    },
}

response, err := client.GetRange(request)
if err != nil {
    log.Fatal(err)
}
fmt.Println(response.Rows)

參數說明

GetRangeRequest 包含以下參數。

名稱	類型	說明
RangeRowQueryCriteria（必選）	`*RangeRowQueryCriteria`	範圍讀取條件。

範圍讀取條件

RangeRowQueryCriteria 包含以下參數。

名稱	類型	說明
TableName（必選）	`string`	資料表名稱。
StartPrimaryKey（必選）	`*PrimaryKey`	起始主鍵，包含主鍵列名稱和值。結果包含該主鍵對應的行。主鍵列的數量、順序和類型必須與資料表的主鍵結構一致。正向讀取時必須小於 `EndPrimaryKey`，反向讀取時必須大於 `EndPrimaryKey`。可調用 `AddPrimaryKeyColumnWithMinValue` 和 `AddPrimaryKeyColumnWithMaxValue` 分別設定無限小和無限大的主鍵列值。
EndPrimaryKey（必選）	`*PrimaryKey`	結束主鍵，包含主鍵列名稱和值。結果不包含該主鍵對應的行。主鍵列的數量、順序和類型必須與資料表的主鍵結構一致。可調用 `AddPrimaryKeyColumnWithMinValue` 和 `AddPrimaryKeyColumnWithMaxValue` 分別設定無限小和無限大的主鍵列值。
Direction（可選）	`Direction`	讀取方向。`FORWARD` 表示正向讀取，`BACKWARD` 表示反向讀取。預設值為 `FORWARD`。
MaxVersion（可選）	`int32`	每個屬性列最多返回的版本數。`MaxVersion` 和 `TimeRange` 至少設定一個。符合查詢條件的資料版本數超過該值時，按從新到舊的順序返回指定數量的版本。
TimeRange（可選）	`*TimeRange`	版本時間範圍，包括起始時間、結束時間或指定版本，單位為毫秒。`MaxVersion` 和 `TimeRange` 至少設定一個。每個屬性列可以具有不同的資料版本。設定後，僅返回指定版本時間範圍內的資料。
Limit（可選）	`int32`	單次調用最多返回的行數，必須大於 0。符合查詢條件的行數超過該值時，響應返回指定數量的行以及用於繼續讀取的 `NextStartPrimaryKey`。
ColumnsToGet（可選）	`[]string`	要返回的主鍵列或屬性列名稱。未設定時返回整行資料。如果行資料不包含任何指定列，則該行不包含在 `Rows` 中。
Filter（可選）	`ColumnFilter`	屬性列過濾器。更多資訊，請參見過濾器。同時設定 `ColumnsToGet` 和 `Filter` 時，先按 `ColumnsToGet` 選擇列，再使用 `Filter` 對選擇後的列進行過濾。如果過濾條件引用的屬性列不在 `ColumnsToGet` 中，則按該列不存在處理，是否過濾該行由 `FilterIfMissing` 決定。
StartColumn（可選）	`*string`	屬性列名稱範圍的起始列，結果包含該列。
EndColumn（可選）	`*string`	屬性列名稱範圍的結束列，結果不包含該列。
TransactionId（可選）	`*string`	局部事務 ID。僅在局部事務內讀取資料時設定。

傳回值

GetRangeResponse 包含以下商務資訊。

欄位	類型	說明
`Rows`	`[]*Row`	返回的行資料。
`NextStartPrimaryKey`	`*PrimaryKey`	下一次讀取的起始主鍵。值為 `nil` 時表示已讀取完指定範圍內的資料。

情境樣本

連續讀取全部結果

以下樣本使用 NextStartPrimaryKey 連續讀取指定範圍內的全部資料。

for {
    response, err := client.GetRange(request)
    if err != nil {
        log.Fatal(err)
    }

    for _, row := range response.Rows {
        fmt.Println(row.PrimaryKey, row.Columns)
    }

    if response.NextStartPrimaryKey == nil {
        break
    }
    request.RangeRowQueryCriteria.StartPrimaryKey = response.NextStartPrimaryKey
}

反向讀取資料

以下樣本從無限大的主索引值開始，反向讀取到指定主索引值，但不包含結束主鍵對應的行。

startKey := &tablestore.PrimaryKey{}
startKey.AddPrimaryKeyColumnWithMaxValue("id")

endKey := &tablestore.PrimaryKey{}
endKey.AddPrimaryKeyColumn("id", "row1")

request.RangeRowQueryCriteria.StartPrimaryKey = startKey
request.RangeRowQueryCriteria.EndPrimaryKey = endKey
request.RangeRowQueryCriteria.Direction = tablestore.BACKWARD

讀取指定時間範圍內的資料版本

以下樣本讀取指定時間範圍內的資料版本。時間範圍為左閉右開區間。

endTime := time.Now().UnixMilli()
startTime := endTime - int64(time.Hour/time.Millisecond)

request.RangeRowQueryCriteria.MaxVersion = 0
request.RangeRowQueryCriteria.TimeRange = &tablestore.TimeRange{
    Start: startTime,
    End:   endTime,
}