Read a range of rows

Prerequisites

Install the Tablestore SDK for Go and initialize the client.

Description

Call GetRange to read rows between a start primary key and an end primary key. The row that corresponds to the start primary key is included, and the row that corresponds to the end primary key is excluded. A call returns at most 5,000 rows or 4 MB of data. If the limit is exceeded, use the returned next start primary key to continue reading.

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

The following sample reads up to 100 rows after row1 from the example_table table in the forward direction.

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)

Parameters

GetRangeRequest contains the following parameter.

Name	Type	Description
RangeRowQueryCriteria (required)	`*RangeRowQueryCriteria`	The range query criteria.

Range query criteria

RangeRowQueryCriteria contains the following parameters.

Name	Type	Description
TableName (required)	`string`	The table name.
StartPrimaryKey (required)	`*PrimaryKey`	The start primary key, including primary key column names and values. The corresponding row is included. The number, order, and types of primary key columns must match the primary key schema of the table. This key must be less than `EndPrimaryKey` for a forward read and greater than `EndPrimaryKey` for a backward read. Call `AddPrimaryKeyColumnWithMinValue` or `AddPrimaryKeyColumnWithMaxValue` to set a primary key column value to negative infinity or positive infinity.
EndPrimaryKey (required)	`*PrimaryKey`	The end primary key, including primary key column names and values. The corresponding row is excluded. The number, order, and types of primary key columns must match the primary key schema of the table. Call `AddPrimaryKeyColumnWithMinValue` or `AddPrimaryKeyColumnWithMaxValue` to set a primary key column value to negative infinity or positive infinity.
Direction (optional)	`Direction`	The read direction. `FORWARD` specifies a forward read, and `BACKWARD` specifies a backward read. Default value: `FORWARD`.
MaxVersion (optional)	`int32`	The maximum number of versions to return for each attribute column. At least one of `MaxVersion` and `TimeRange` is required. If the number of matching data versions exceeds this value, the specified number of versions are returned from the latest to the earliest.
TimeRange (optional)	`*TimeRange`	The version time range, which specifies a start time, end time, or exact version in milliseconds. At least one of `MaxVersion` and `TimeRange` is required. Each attribute column can have different data versions. If this parameter is specified, only data in the specified version time range is returned.
Limit (optional)	`int32`	The maximum number of rows to return in one call. The value must be greater than 0. If the number of matching rows exceeds this value, the response returns the specified number of rows and a `NextStartPrimaryKey` value for the next read.
ColumnsToGet (optional)	`[]string`	The primary key columns or attribute columns to return. If this parameter is not specified, the entire row is returned. If a row does not contain any specified column, the row is not included in `Rows`.
Filter (optional)	`ColumnFilter`	The attribute column filter. For more information, see Use filters. If `ColumnsToGet` and `Filter` are both specified, Tablestore first selects columns based on `ColumnsToGet` and then applies `Filter` to the selected columns. If the filter references an attribute column that is not included in `ColumnsToGet`, the column is treated as missing. Whether the row is filtered out is determined by `FilterIfMissing`.
StartColumn (optional)	`*string`	The start attribute column of the name range. This column is included.
EndColumn (optional)	`*string`	The end attribute column of the name range. This column is excluded.
TransactionId (optional)	`*string`	The local transaction ID. Specify this parameter only for a read in a local transaction.

Response

GetRangeResponse contains the following business information.

Field	Type	Description
`Rows`	`[]*Row`	The returned rows.
`NextStartPrimaryKey`	`*PrimaryKey`	The start primary key for the next read. A value of `nil` indicates that all rows in the specified range have been read.

Examples

Read all results

The following sample uses NextStartPrimaryKey to continuously read all rows in the specified range.

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
}

Read rows in reverse order

The following sample starts from the positive-infinity primary key value and reads rows in reverse order to a specified primary key. The row that corresponds to the end primary key is excluded.

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

Read data versions in a time range

The following sample reads data versions in a specified time range. The time range is left-closed and right-open.

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

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