Tablestore:データの読み取り

クエリメソッド

Tablestore は、データを読み取るための GetRow、BatchGetRow、および GetRange 操作を提供します。データを読み取る前に、実際のクエリシナリオに基づいて適切なクエリメソッドを選択してください。

前提条件

• OTSClient インスタンスが初期化されていること。詳細については、OTSClient インスタンスの初期化 を参照してください。

• データテーブルが作成され、データがデータテーブルに書き込まれていること。

単一のデータ行の読み取り

GetRow 操作を呼び出して、単一のデータ行を読み取ることができます。GetRow 操作を呼び出した後、次のいずれかの結果が返される場合があります。

• 行が存在する場合、行の主キー列と属性列が返されます。

• 行が存在しない場合、行は返されず、エラーも報告されません。

API 操作

// テーブル内のデータ行を返します。
// @param GetRowRequest             GetRow 操作の呼び出しに必要なパラメータをカプセル化します。
// @return  GetRowResponse          GetRow 操作へのレスポンスの内容。
GetRow(request *GetRowRequest) (*GetRowResponse, error)                   

パラメータ

サンプルコード

次のサンプルコードは、データ行を読み取る方法の例を示しています。

// テーブル内のデータ行を返します。
// @param GetRowRequest             GetRow 操作の呼び出しに必要なパラメータをカプセル化します。
// @return  GetRowResponse          GetRow 操作へのレスポンスの内容。
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) // getrow がエラーで失敗しました：
} else {
    fmt.Println("get row col0 result is ",getResp.Columns[0].ColumnName, getResp.Columns[0].Value,) // get row col0 の結果は
}                   

詳細なサンプルコードを表示するには、GetRow@GitHub を参照してください。

複数行のデータの一括読み取り

BatchGetRow 操作を呼び出して、1 つ以上のテーブルから一度に複数のデータ行を読み取ることができます。BatchGetRow 操作は、複数の GetRow 操作で構成されます。BatchGetRow 操作を呼び出す場合、各 GetRow 操作を構築するプロセスは、GetRow 操作を呼び出す場合に GetRow 操作を構築するプロセスと同じです。

BatchGetRow 操作を呼び出すと、各 GetRow 操作は個別に実行され、Tablestore は各 GetRow 操作へのレスポンスを個別に返します。

使用上の注意

• BatchGetRow 操作を呼び出して一度に複数の行を読み取ると、一部の行の読み取りに失敗する場合があります。この場合、Tablestore は例外を返さず、失敗した行に関する情報を含む BatchGetRowResponse を返します。したがって、BatchGetRow 操作を呼び出すときは、戻り値をチェックして、各行からデータが正常に読み取られたかどうかを確認する必要があります。

• BatchGetRow 操作では、すべての行に同じパラメータ設定を使用します。たとえば、ColumnsToGet パラメータが [colA] に設定されている場合、colA 列の値のみがすべての行から読み取られます。

• BatchGetRow 操作を呼び出して、一度に最大 100 行を読み取ることができます。

パラメータ

パラメータの詳細については、「単一のデータ行の読み取り」セクションのパラメータテーブルを参照してください。

API 操作

// テーブルから複数のデータ行を返します。
// @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) // batchget がエラーで失敗しました：
} else {
    fmt.Println("batchget finished") // batchget が完了しました
}                    

詳細なサンプルコードを表示するには、BatchGetRow@GitHub を参照してください。

主キー値が特定の範囲内にあるデータの読み取り

GetRange 操作を呼び出して、主キー値が指定された範囲内にあるデータを読み取ることができます。

GetRange 操作を使用すると、主キー値が指定された範囲内にあるデータを前方または後方に読み取ることができます。読み取る行数を指定することもできます。範囲が広く、スキャンされた行数またはスキャンされたデータの量が上限を超えると、スキャンは停止し、読み取られた行と次の行の主キーに関する情報が返されます。前回の操作で返された次の行の主キー情報に基づいて、最後の操作が中断された場所から開始し、残りの行を読み取るリクエストを開始できます。

使用上の注意

GetRange 操作は、左端一致の原則に従います。Tablestore は、最初の主キー列から最後の主キー列まで順番に値を比較して、主キー値が指定された範囲内にあるデータを読み取ります。たとえば、データテーブルの主キーが PK1、PK2、PK3 という主キー列で構成されているとします。データを読み取るとき、Tablestore はまず、行の PK1 値が最初の主キー列に指定された範囲内にあるかどうかを判断します。行の PK1 値が範囲内にある場合、Tablestore は、行の他の主キー列の値が各主キー列に指定された範囲内にあるかどうかの判断を停止し、行を返します。行の PK1 値が範囲内にない場合、Tablestore は、PK1 と同じ方法で、行の他の主キー列の値が各主キー列に指定された範囲内にあるかどうかを判断し続けます。

次のいずれかの条件が満たされると、GetRange 操作が停止してデータが返される場合があります。

• スキャンされたデータ量が 4 MB に達する。

• スキャンされた行数が 5,000 に達する。

• 返された行数が上限に達する。

• 予約済みの読み取りスループットがすべて消費されているため、読み取りスループットが次のデータ行を読み取るのに不十分である。

API 操作

// テーブル内の、主キー値が指定された範囲内にある複数のデータ行をクエリします。
// @param GetRangeRequest            GetRange 操作の呼び出しに必要なパラメータをカプセル化します。
// @return GetRangeResponse          GetRange 操作へのレスポンスの内容。
GetRange(request *GetRangeRequest) (*GetRangeResponse,error)                   

パラメータ

サンプルコード

次のサンプルコードは、主キー値が指定された範囲内にあるデータを読み取る方法の例を示しています。

// テーブル内の、主キー値が指定された範囲内にある複数のデータ行をクエリします。
// @param GetRangeRequest            GetRange 操作の呼び出しに必要なパラメータをカプセル化します。
// @return GetRangeResponse          GetRange 操作へのレスポンスの内容。
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) // get range の結果は

for {
    if err != nil {
        fmt.Println("get range failed with error:", err) // get range がエラーで失敗しました：
    }
    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) // キーを使用して range get row を取得します
    }
    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) // 次の pk は：
        getRangeRequest.RangeRowQueryCriteria.StartPrimaryKey = getRangeResp.NextStartPrimaryKey
        getRangeResp, err = client.GetRange(getRangeRequest)
    }
    fmt.Println("continue to query rows") // 行のクエリを続行します
}
fmt.Println("range get row finished") // range get row が完了しました

詳細なサンプルコードを表示するには、GetRange@GitHub を参照してください。