Range read

Prerequisites

Initialize Tablestore Client

Method signature

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

Sample code

The following example reads rows from the test_table table where the primary key is greater than row1.

func GetRangeSample(client *tablestore.TableStoreClient) {
    // Build the query criteria.
    rangeRowQueryCriteria := new(tablestore.RangeRowQueryCriteria)
    rangeRowQueryCriteria.TableName = "test_table"
    // Set the start primary key for the query.
    startPK := new(tablestore.PrimaryKey)
    startPK.AddPrimaryKeyColumn("id", "row1")
    rangeRowQueryCriteria.StartPrimaryKey = startPK
    // Set the end primary key for the query. The end primary key is exclusive.
    endPK := new(tablestore.PrimaryKey)
    endPK.AddPrimaryKeyColumnWithMaxValue("id")
    rangeRowQueryCriteria.EndPrimaryKey = endPK
    // Set the maximum number of versions to read per column.
    rangeRowQueryCriteria.MaxVersion = 1

    // Call the GetRange method to query data.
    getRangeRequest := new(tablestore.GetRangeRequest)
    getRangeRequest.RangeRowQueryCriteria = rangeRowQueryCriteria
    getRangeResponse, err := client.GetRange(getRangeRequest)

    // Process the response.
    if err != nil {
        fmt.Println("Range get failed with error: ", err)
    } else {
        fmt.Printf("* RequestId: %s \n", getRangeResponse.RequestId)
        fmt.Printf("* Read CU Cost: %d \n", getRangeResponse.ConsumedCapacityUnit.Read)
        fmt.Printf("* Write CU Cost: %d \n", getRangeResponse.ConsumedCapacityUnit.Write)
        fmt.Println("* Rows Data:")
        for _, row := range getRangeResponse.Rows {
            fmt.Printf("PrimaryKey: %v; Columns: ", row.PrimaryKey.PrimaryKeys)
            for _, column := range row.Columns {
                fmt.Printf("%v ", column)
            }
            fmt.Printf("\n")
        }
    }
}

Each GetRange response returns at most 5,000 rows or 4 MB of data. When the result exceeds that limit, the response includes a NextStartPrimaryKey for the next read. Use the following loop to iterate until all rows are read.

for {
    // Call the GetRange method to query data.
    getRangeRequest := new(tablestore.GetRangeRequest)
    getRangeRequest.RangeRowQueryCriteria = rangeRowQueryCriteria
    getRangeResponse, err := client.GetRange(getRangeRequest)
    // Process the response.
    if err != nil {
        fmt.Println("Range get failed with error: ", err)
        break
    } else {
        fmt.Printf("* RequestId: %s \n", getRangeResponse.RequestId)
        fmt.Printf("* Read CU Cost: %d \n", getRangeResponse.ConsumedCapacityUnit.Read)
        fmt.Printf("* Write CU Cost: %d \n", getRangeResponse.ConsumedCapacityUnit.Write)
        fmt.Printf("* Rows Count: %d \n", len(getRangeResponse.Rows))
        fmt.Println("* Rows Data:")
        for _, row := range getRangeResponse.Rows {
            fmt.Printf("PrimaryKey: %v; Columns: ", row.PrimaryKey.PrimaryKeys)
            for _, column := range row.Columns {
                fmt.Printf("%v ", column)
            }
            fmt.Printf("\n")
        }
    }
    // Set the start primary key for the next iteration.
    if getRangeResponse.NextStartPrimaryKey != nil {
        startPK := new(tablestore.PrimaryKey)
        startPK.AddPrimaryKeyColumn("id", getRangeResponse.NextStartPrimaryKey.PrimaryKeys[0].Value)
        rangeRowQueryCriteria.StartPrimaryKey = startPK
    } else {
        break
    }
}

You can also apply the following optional settings in your query.

• Set the read direction.

  // Set the direction to backward.
  rangeRowQueryCriteria.Direction = tablestore.BACKWARD
  // Set the start primary key. For a backward read, the start primary key must be greater than the end primary key.
  startPK := new(tablestore.PrimaryKey)
  startPK.AddPrimaryKeyColumnWithMaxValue("id")
  rangeRowQueryCriteria.StartPrimaryKey = startPK
  // Set the end primary key. The end primary key is exclusive.
  endPK := new(tablestore.PrimaryKey)
  endPK.AddPrimaryKeyColumn("id", "row1")
  rangeRowQueryCriteria.EndPrimaryKey = endPK

• Set a time range to return only versions within that window.

  // Set the time range for the query to the last 24 hours.
  timeRange := new(tablestore.TimeRange)
  timeRange.Start = int64(time.Now().Unix() * 1000 - 86400 * 1000) 
  timeRange.End = int64(time.Now().Unix() * 1000) 
  rangeRowQueryCriteria.TimeRange = timeRange;

• Return only the specified attribute columns.

  rangeRowQueryCriteria.AddColumnToGet("col1")

• Limit the number of rows returned per request.

  rangeRowQueryCriteria.Limit = 10

References

Batch read data