如何通過Go SDK單行讀取、批量讀取或者範圍讀取資料 - Tablestore

Tablestore提供了GetRow介面用於讀取單行資料以及BatchGetRow、GetRange等介面用於讀取多行資料。

查詢方式

Tablestore提供的資料讀取介面包括GetRow、BatchGetRow和GetRange。讀取資料時，請根據實際查詢情境使用相應查詢方式讀取資料。

重要

當要讀取帶有自增主鍵列的表資料時，請確保已擷取到包含自增主鍵列值在內的完整主鍵。更多資訊，請參見主鍵列自增。如果未記錄自增主鍵列的值，您可以使用範圍讀取資料按照第一個主鍵列確定範圍讀取資料。

查詢方式	說明	適用情境
讀取單行資料	調用GetRow介面讀取一行資料。	適用於能確定完整主鍵且要讀取行數較少的情境。
批量讀取資料	調用BatchGetRow介面一次請求讀取多行資料或者一次對多張表進行讀取。 BatchGetRow操作由多個GetRow子操作組成，構造子操作的過程與使用GetRow介面時相同。	適用於能確定完整主鍵，且要讀取行數較多或者要讀取多個表中資料的情境。
範圍讀取資料	調用GetRange介面讀取一個範圍內的資料。 GetRange操作支援按照確定範圍進行正序讀取和逆序讀取，可以設定要讀取的行數。如果範圍較大，已掃描的行數或者資料量超過一定限制，會停止掃描，並返回已擷取的行和下一個主鍵資訊。您可以根據返回的下一個主鍵資訊，繼續發起請求，擷取範圍內剩餘的行。	適用於能確定完整主鍵範圍或者主鍵首碼的情境。重要如果不能確定主鍵首碼，您也可以通過設定完整主鍵範圍均為虛擬點INF_MIN和INF_MAX進行全表資料掃描，但是執行此操作會消耗較多計算資源，請謹慎使用。

前提條件

已初始化Client。具體操作，請參見初始化OTSClient。
已建立資料表並寫入資料。

讀取單行資料

調用GetRow介面讀取一行資料。讀取的結果可能有如下兩種：

如果該行存在，則返回該行的各主鍵列以及屬性列。
如果該行不存在，則返回中不包含行，並且不會報錯。

介面

//返回表中的一行資料。
// @param GetRowRequest             執行GetRow操作所需參數的封裝。
// @return  GetRowResponse          GetRow操作的響應內容。
GetRow(request *GetRowRequest) (*GetRowResponse, error)

參數

參數	說明
TableName	資料表名稱。
PrimaryKey	行的主鍵。主鍵包括主鍵列名、主鍵類型和主索引值。重要設定的主鍵個數和類型必須和資料表的主鍵個數和類型一致。
ColumnsToGet	讀取的列集合，列名可以是主鍵列或屬性列。如果不設定返回的列名，則返回整行資料。如果設定了返回的列名，當某行中指定的列均不存在時，則不返回該行，即傳回值為null；當某行中存在部分指定的列時，則返回該行且只返回存在的列。說明查詢一行資料時，預設返回此行所有列的資料。如果需要只返回特定列，可以通過設定ColumnsToGet參數限制。如果將col0和col1加入到ColumnsToGet中，則只返回col0和col1列的值。當ColumnsToGet和Filter同時使用時，執行順序是先擷取ColumnsToGet指定的列，再在返回的列中進行條件過濾。
MaxVersion	最多讀取的版本數。重要 MaxVersion與TimeRange必須至少設定一個。如果僅設定MaxVersion，則最多返回所有版本中從新到舊指定數量版本的資料。如果僅設定TimeRange，則返回該範圍內所有資料或指定版本資料。如果同時設定MaxVersion和TimeRange，則最多返回版本號碼範圍內從新到舊指定數量版本的資料。
TimeRange	讀取版本號碼範圍或特定版本號碼的資料。更多資訊，請參見TimeRange。重要 MaxVersion與TimeRange必須至少設定一個。如果僅設定MaxVersion，則最多返回所有版本中從新到舊指定數量版本的資料。如果僅設定TimeRange，則返回該範圍內所有資料或指定版本資料。如果同時設定MaxVersion和TimeRange，則最多返回版本號碼範圍內從新到舊指定數量版本的資料。如果要查詢一個範圍的資料，則需要設定Start和End。Start和End分別表示起始時間戳記和結束時間戳記，範圍為前閉後開區間，即`[Start, End)`。如果要查詢特定版本號碼的資料，則需要設定Specific。Specific表示特定的時間戳記。 Specific和`[Start, End)`中只需要設定一個。時間戳記的單位為毫秒，最小值為0，最大值為INT64.MAX。
Filter	使用過濾器，在服務端對讀取結果再進行一次過濾，只返回符合過濾器中條件的資料行。更多資訊，請參見過濾器。說明當ColumnsToGet和Filter同時使用時，執行順序是先擷取ColumnsToGet指定的列，再在返回的列中進行條件過濾。

樣本

以下樣本用於讀取一行資料。

getRowRequest := new(tablestore.GetRowRequest)
criteria := new(tablestore.SingleRowQueryCriteria);
putPk := new(tablestore.PrimaryKey)
putPk.AddPrimaryKeyColumn("pk1", "pk1value1")
putPk.AddPrimaryKeyColumn("pk2", int64(2))
putPk.AddPrimaryKeyColumn("pk3", []byte("pk3"))

criteria.PrimaryKey = putPk
getRowRequest.SingleRowQueryCriteria = criteria
getRowRequest.SingleRowQueryCriteria.TableName = tableName 
getRowRequest.SingleRowQueryCriteria.MaxVersion = 1  
getResp, err := client.GetRow(getRowRequest)
if err != nil {
    fmt.Println("getrow failed with error:", err)
} else {
    fmt.Println("get row col0 result is ",getResp.Columns[0].ColumnName, getResp.Columns[0].Value,)
}

詳細代碼請參見GetRow@GitHub。

批量讀取資料

調用BatchGetRow介面一次請求讀取多行資料，也支援一次對多張表進行讀取。BatchGetRow由多個GetRow子操作組成。構造子操作的過程與使用GetRow介面時相同。

BatchGetRow的各個子操作獨立執行，Tablestore會分別返回各個子操作的執行結果。

注意事項

由於批量讀取可能存在部分行失敗的情況，失敗行的錯誤資訊在返回的BatchGetRowResponse中，但並不拋出異常。因此調用BatchGetRow介面時，需要檢查傳回值，判斷每行的狀態是否成功。
批量讀取的所有行採用相同的參數條件，例如ColumnsToGet=[colA]，表示要讀取的所有行都唯讀取colA列。
BatchGetRow操作單次支援讀取的最大行數為100行。

參數

更多資訊，請參見讀取單行資料參數。

介面

//返回資料表（Table）中的多行資料。
// @param BatchGetRowRequest             執行BatchGetRow操作所需參數的封裝。
// @return  BatchGetRowResponse          BatchGetRow操作的響應內容。
BatchGetRow(request *BatchGetRowRequest) (*BatchGetRowResponse, error)

樣本

以下樣本用於批量一次讀取10行資料。

batchGetReq := &tablestore.BatchGetRowRequest{}
mqCriteria := &tablestore.MultiRowQueryCriteria{}

for i := 0; i < 10; i++ {
    pkToGet := new(tablestore.PrimaryKey)
    pkToGet.AddPrimaryKeyColumn("pk1", "pk1value1")
    pkToGet.AddPrimaryKeyColumn("pk2", int64(i))
    pkToGet.AddPrimaryKeyColumn("pk3", []byte("pk3"))
    mqCriteria.AddRow(pkToGet)
    mqCriteria.MaxVersion = 1
}
mqCriteria.TableName = tableName
batchGetReq.MultiRowQueryCriteria = append(batchGetReq.MultiRowQueryCriteria, mqCriteria)
batchGetResponse, err := client.BatchGetRow(batchGetReq)

if err != nil {
    fmt.Println("batchget failed with error:", err)
} else {
    fmt.Println("batchget finished")
}

詳細代碼請參見BatchGetRow@GitHub。

範圍讀取資料

調用GetRange介面讀取一個範圍內的資料。

GetRange操作支援按照確定範圍進行正序讀取和逆序讀取，可以設定要讀取的行數。如果範圍較大，已掃描的行數或者資料量超過一定限制，會停止掃描，並返回已擷取的行和下一個主鍵資訊。您可以根據返回的下一個主鍵資訊，繼續發起請求，擷取範圍內剩餘的行。

說明

Tablestore表中的行都是按照主鍵排序的，而主鍵是由全部主鍵列按照順序組成的，所以不能理解為Tablestore會按照某列主鍵排序，這是常見的誤區。

注意事項

GetRange操作遵循最左匹配原則，讀取資料時，依次比較第一主鍵列到第四主鍵列。例如表的主鍵包括PK1、PK2、PK3三個主鍵列，讀取資料時，優先比較PK1是否在開始主鍵與結束主鍵的範圍內，如果PK1在設定的主鍵範圍內，則不會再比較其他的主鍵，返回在PK1主鍵範圍內的資料；如果PK1在設定的主鍵邊界上，則繼續比較PK2是否在開始主鍵與結束主鍵的範圍內，以此類推。

GetRange操作可能在如下情況停止執行並返回資料。

掃描的行資料大小之和達到4 MB。
掃描的行數等於5000。
返回的行數等於最大返回行數。
當前剩餘的預留讀輸送量已全部使用，餘量不足以讀取下一條資料。

當使用GetRange掃描的資料量較大時，Tablestore每次請求僅會掃描一次（行數大於5000或者大小大於4 MB停止掃描），超過限制的資料不會繼續返回，需要通過翻頁繼續擷取後面的資料。

介面

//從表中查詢一個範圍內的多行資料。
// @param GetRangeRequest           執行GetRange操作所需參數的封裝。
// @return GetRangeResponse         GetRange操作的響應內容。
GetRange(request *GetRangeRequest) (*GetRangeResponse,error)

參數

參數	說明
TableName	資料表名稱。
Direction	讀取方向。如果值為正序（FORWARD），則起始主鍵必須小於結束主鍵，返回的行按照主鍵由小到大的順序進行排列。如果值為逆序（BACKWARD），則起始主鍵必須大於結束主鍵，返回的行按照主鍵由大到小的順序進行排列。假設同一表中有兩個主鍵A和B，A小於B，如果正序讀取`[A, B)`，則按從A到B的順序返回主鍵大於等於A且小於B的行資料；如果逆序讀取`[B, A)`，則按從B到A的順序返回大於A且小於等於B的行資料。
StartPrimaryKey	本次範圍讀取的起始主鍵和結束主鍵，起始主鍵和結束主鍵需要是有效主鍵或者是由INF_MIN和INF_MAX類型組成的虛擬點，虛擬點的列數必須與主鍵相同。其中INF_MIN表示無限小，任何類型的值都比它大；INF_MAX表示無限大，任何類型的值都比它小。 StartPrimaryKey表示起始主鍵，如果該行存在，則返回結果中一定會包含此行。 EndPrimaryKey表示結束主鍵，無論該行是否存在，返回結果中都不會包含此行。資料表中的行按主鍵從小到大排序，讀取範圍是一個左閉右開的區間，正序讀取時，返回的是大於等於起始主鍵且小於結束主鍵的所有的行。
EndPrimaryKey
Limit	資料的最大返回行數，此值必須大於 0。 Tablestore按照正序或者逆序返回指定的最大返回行數後即結束該操作的執行，即使該區間內仍有未返回的資料。此時可以通過返回結果中的NextStartPrimaryKey記錄本次讀取到的位置，用於下一次讀取。
ColumnsToGet	讀取的列集合，列名可以是主鍵列或屬性列。如果不設定返回的列名，則返回整行資料。如果設定了返回的列名，當某行中指定的列均不存在時，則不返回該行，即傳回值為null；當某行中存在部分指定的列時，則返回該行且只返回存在的列。說明查詢一行資料時，預設返回此行所有列的資料。如果需要只返回特定列，可以通過設定ColumnsToGet參數限制。如果將col0和col1加入到ColumnsToGet中，則只返回col0和col1列的值。如果某行資料的主鍵屬於讀取範圍，但是該行資料不包含指定返回的列，那麼返回結果中不包含該行資料。當ColumnsToGet和Filter同時使用時，執行順序是先擷取ColumnsToGet指定的列，再在返回的列中進行條件過濾。
MaxVersions	最多讀取的版本數。重要 MaxVersion與TimeRange必須至少設定一個。如果僅設定MaxVersion，則最多返回所有版本中從新到舊指定數量版本的資料。如果僅設定TimeRange，則返回該範圍內所有資料或指定版本資料。如果同時設定MaxVersion和TimeRange，則最多返回版本號碼範圍內從新到舊指定數量版本的資料。
TimeRange	讀取版本號碼範圍或特定版本號碼的資料。更多資訊，請參見TimeRange。重要 MaxVersion與TimeRange必須至少設定一個。如果僅設定MaxVersion，則最多返回所有版本中從新到舊指定數量版本的資料。如果僅設定TimeRange，則返回該範圍內所有資料或指定版本資料。如果同時設定MaxVersion和TimeRange，則最多返回版本號碼範圍內從新到舊指定數量版本的資料。如果要查詢一個範圍的資料，則需要設定Start和End。Start和End分別表示起始時間戳記和結束時間戳記，範圍為前閉後開區間，即`[Start, End)`。如果要查詢特定版本號碼的資料，則需要設定Specific。Specific表示特定的時間戳記。 Specific和`[Start, End)`中只需要設定一個。時間戳記的單位為毫秒，最小值為0，最大值為`INT64.MAX`。
Filter	使用過濾器，在服務端對讀取結果再進行一次過濾，只返回符合過濾器中條件的資料行。更多資訊，請參見過濾器。說明當ColumnsToGet和Filter同時使用時，執行順序是先擷取ColumnsToGet指定的列，再在返回的列中進行條件過濾。
NextStartPrimaryKey	根據返回結果中的NextStartPrimaryKey判斷資料是否全部讀取。當返回結果中NextStartPrimaryKey不為空白時，可以使用此傳回值作為下一次GetRange操作的起始點繼續讀取資料。當返回結果中NextStartPrimaryKey為空白時，表示讀取範圍內的資料全部返回。

樣本

以下樣本用於按照範圍讀取資料。

getRangeRequest := &tablestore.GetRangeRequest{}
rangeRowQueryCriteria := &tablestore.RangeRowQueryCriteria{}
rangeRowQueryCriteria.TableName = tableName

startPK := new(tablestore.PrimaryKey)
startPK.AddPrimaryKeyColumnWithMinValue("pk1")
startPK.AddPrimaryKeyColumnWithMinValue("pk2")
startPK.AddPrimaryKeyColumnWithMinValue("pk3")
endPK := new(tablestore.PrimaryKey)
endPK.AddPrimaryKeyColumnWithMaxValue("pk1")
endPK.AddPrimaryKeyColumnWithMaxValue("pk2")
endPK.AddPrimaryKeyColumnWithMaxValue("pk3")
rangeRowQueryCriteria.StartPrimaryKey = startPK
rangeRowQueryCriteria.EndPrimaryKey = endPK
rangeRowQueryCriteria.Direction = tablestore.FORWARD
rangeRowQueryCriteria.MaxVersion = 1
rangeRowQueryCriteria.Limit = 10
getRangeRequest.RangeRowQueryCriteria = rangeRowQueryCriteria

getRangeResp, err := client.GetRange(getRangeRequest)

fmt.Println("get range result is " ,getRangeResp)

for {
    if err != nil {
        fmt.Println("get range failed with error:", err)
    }
    for _, row := range getRangeResp.Rows {
        fmt.Println("range get row with key", row.PrimaryKey.PrimaryKeys[0].Value, row.PrimaryKey.PrimaryKeys[1].Value, row.PrimaryKey.PrimaryKeys[2].Value)
    }
    if getRangeResp.NextStartPrimaryKey == nil {
        break
    } else {
        fmt.Println("next pk is :", getRangeResp.NextStartPrimaryKey.PrimaryKeys[0].Value, getRangeResp.NextStartPrimaryKey.PrimaryKeys[1].Value, getRangeResp.NextStartPrimaryKey.PrimaryKeys[2].Value)
        getRangeRequest.RangeRowQueryCriteria.StartPrimaryKey = getRangeResp.NextStartPrimaryKey
        getRangeResp, err = client.GetRange(getRangeRequest)
    }
    fmt.Println("continue to query rows")
}
fmt.Println("range get row finished")

詳細代碼請參見GetRange@GitHub。