表格存储提供了BatchWriteRow、BatchGetRow、GetRange等多行操作的接口。
如果需要了解表格存储各场景的应用案例,请参见快速玩转Tablestore入门与实战。
前提条件
- 已初始化Client,详情请参见初始化。
- 已创建数据表并写入数据。
批量写(BatchWriteRow)
批量写接口用于在一次请求中进行批量的写入操作,也支持一次对多个数据表进行写入。BatchWriteRow操作由多个PutRow、UpdateRow、DeleteRow子操作组成,构造子操作的过程与使用PutRow接口、UpdateRow接口和DeleteRow接口时相同,也支持使用条件更新。
BatchWriteRow的各个子操作独立执行,表格存储会分别返回各个子操作的执行结果。
注意事项
- 由于批量写入可能存在部分行失败的情况,失败行的Index及错误信息在返回的BatchWriteRowResponse中,但并不抛出异常。因此调用BatchWriteRow接口时,需要检查返回值,判断每行的状态是否成功;如果不检查返回值,则可能会忽略掉部分操作的失败。
当服务端检查到某些操作出现参数错误时,BatchWriteRow接口可能会抛出参数错误的异常,此时该请求中所有的操作都未执行。
- BatchWriteRow操作单次支持写入的最大行数为200行,且所有行的数据量总和不能超过4 MB。
接口
// 对多个数据表中的多行数据进行增加、删除或者更新操作。
// @param BatchWriteRowRequest 执行BatchWriteRow操作所需参数的封装。
// @return BatchWriteRowResponse BatchWriteRow操作的响应内容。
BatchWriteRow(request *BatchWriteRowRequest) (*BatchWriteRowResponse,error)
参数
详细参数说明请参见单行数据操作。
示例
批量写入100行数据。
batchWriteReq := &tablestore.BatchWriteRowRequest{}
for i := 0; i < 100; i++ {
putRowChange := new(tablestore.PutRowChange)
putRowChange.TableName = tableName
putPk := new(tablestore.PrimaryKey)
putPk.AddPrimaryKeyColumn("pk1", "pk1value1")
putPk.AddPrimaryKeyColumn("pk2", int64(i))
putPk.AddPrimaryKeyColumn("pk3", []byte("pk3"))
putRowChange.PrimaryKey = putPk
putRowChange.AddColumn("col1", "fixvalue")
putRowChange.SetCondition(tablestore.RowExistenceExpectation_IGNORE)
batchWriteReq.AddRowChange(putRowChange)
}
response, err := client.BatchWriteRow(batchWriteReq)
if err != nil {
fmt.Println("batch request failed with:", response)
} else {
fmt.Println("batch write row finished")
}
详细代码请参见BatchWriteRow@GitHub。
批量读(BatchGetRow)
批量读接口用于一次请求读取多行数据,也支持一次对多个数据表进行读取。BatchGetRow由多个GetRow子操作组成。构造子操作的过程与使用GetRow接口时相同,也支持使用过滤器。
批量读取的所有行采用相同的参数条件,例如ColumnsToGet=[colA],则要读取的所有行都只读取colA列。
BatchGetRow的各个子操作独立执行,表格存储会分别返回各个子操作的执行结果。
注意事项
- 由于批量读取可能存在部分行失败的情况,失败行的错误信息在返回的BatchGetRowResponse中,但并不抛出异常。因此调用BatchGetRow接口时,需要检查返回值,判断每行的状态是否成功。
- 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)
范围读接口用于读取一个主键范围内的数据。
范围读接口支持按照确定范围进行正序读取和逆序读取,可以设置要读取的行数。如果范围较大,已扫描的行数或者数据量超过一定限制,会停止扫描,并返回已获取的行和下一个主键信息。您可以根据返回的下一个主键信息,继续发起请求,获取范围内剩余的行。
注意事项
- 扫描的行数据大小之和达到4 MB。
- 扫描的行数等于5000。
- 返回的行数等于最大返回行数。
- 当前剩余的预留读吞吐量已全部使用,余量不足以读取下一条数据。
接口
//从表中查询一个范围内的多行数据。
// @param GetRangeRequest 执行GetRange操作所需参数的封装。
// @return GetRangeResponse GetRange操作的响应内容。
GetRange(request *GetRangeRequest) (*GetRangeResponse,error)
参数
参数 | 说明 |
---|---|
TableName | 数据表名称。 |
Direction | 读取方向。
例如同一表中有两个主键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表示无限大,任何类型的值都比它小。
数据表中的行按主键从小到大排序,读取范围是一个左闭右开的区间,正序读取时,返回的是大于等于起始主键且小于结束主键的所有的行。 |
EndPrimaryKey | |
Limit | 数据的最大返回行数,此值必须大于 0。
表格存储按照正序或者逆序返回指定的最大返回行数后即结束该操作的执行,即使该区间内仍有未返回的数据。此时可以通过返回结果中的NextStartPrimaryKey记录本次读取到的位置,用于下一次读取。 |
ColumnsToGet | 读取的列集合,列名可以是主键列或属性列。
如果不设置返回的列名,则返回整行数据。 说明
|
MaxVersions | 最多读取的版本数。
说明 MaxVersion与TimeRange必须至少设置一个。
|
TimeRange | 读取版本号范围或特定版本号的数据。更多信息,请参见TimeRange。
说明 MaxVersion与TimeRange必须至少设置一个。
Specific和 时间戳的单位为毫秒,最小值为0,最大值为INT64.MAX。 |
Filter | 使用过滤器,在服务端对读取结果再进行一次过滤,只返回符合过滤器中条件的数据行。更多信息,请参见过滤器。
说明 当ColumnsToGet和Filter同时使用时,执行顺序是先获取ColumnsToGet指定的列,再在返回的列中进行条件过滤。
|
NextStartPrimaryKey | 根据返回结果中的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。