表格存储 Go SDK 范围读取数据-表格存储 Tablestore(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,
}