Tablestore:Read data

Query methods

Tablestore provides the GetRow, BatchGetRow, and GetRange operations to allow you to read data. Before you read data, select the appropriate query method based on the actual query scenario.

Prerequisites

• The OTSClient instance is initialized. For more information, see Initialize an OTSClient instance.
• A data table is created. Data is written to the table.

Read a single row of data

You can call the GetRow operation to read a single row of data. After you call the GetRow operation, one of the following results may be returned:

• If the row exists, the primary key columns and attribute columns of the row are returned.

• If the row does not exist, no row is returned and no error is reported.

API operation

// Return a row of data in a table. 
// @param GetRowRequest             Encapsulate the parameters required to call the GetRow operation. 
// @return  GetRowResponse          The content of the response to the GetRow operation. 
GetRow(request *GetRowRequest) (*GetRowResponse, error)                   

Parameters

Sample code

The following sample code provides an example on how to read a row of data:

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)
} else {
    fmt.Println("get row col0 result is ",getResp.Columns[0].ColumnName, getResp.Columns[0].Value,)
}                   

To view the detailed sample code, visit GetRow@GitHub.

Read multiple rows of data at a time

You can call the BatchGetRow operation to read multiple rows of data from one or more tables at a time. The BatchGetRow operation consists of multiple GetRow operations. When you call the BatchGetRow operation, the process of constructing each GetRow operation is the same as the process of constructing the GetRow operation when you call the GetRow operation.

If you call the BatchGetRow operation, each GetRow operation is separately performed, and Tablestore separately returns the response to each GetRow operation.

Usage notes

• When you call the BatchGetRow operation to read multiple rows at a time, some rows may fail to be read. If this happens, Tablestore does not return exceptions, but returns BatchGetRowResponse in which the information about the failed rows are included. Therefore, when you call the BatchGetRow operation, you must check the return values to determine whether data is successfully read from each row.

• The BatchGetRow operation uses the same parameter settings for all rows. For example, if the ColumnsToGet parameter is set to [colA], only the value of the colA column is read from all rows.

• You can call the BatchGetRow operation to read a maximum of 100 rows at a time.

Parameters

For more information about parameters, see the Parameters table of the "Read a single row of data" section.

API operation

// Return multiple rows of data from a table. 
// @param BatchGetRowRequest             Encapsulate the parameters required to call the BatchGetRow operation. 
// @return  BatchGetRowResponse          The content of the response to the BatchGetRow operation. 
BatchGetRow(request *BatchGetRowRequest) (*BatchGetRowResponse, error)                    

Sample code

The following sample code provides an example on how to read 10 rows of data at a time:

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")
}                    

To view the detailed sample code, visit BatchGetRow@GitHub.

Read data whose primary key values are within a specific range

You can call the GetRange operation to read data whose primary key values are in the specified range.

The GetRange operation allows you to read data whose primary key values are in the specified range in a forward or backward direction. You can also specify the number of rows to read. If the range is large and the number of scanned rows or the volume of scanned data exceeds the upper limit, the scan stops, and the rows that are read and information about the primary key of the next row are returned. You can initiate a request to start from where the last operation left off and read the remaining rows based on the information about the primary key of the next row returned by the previous operation.

Usage notes

The GetRange operation follows the leftmost matching principle. Tablestore compares values in sequence from the first primary key column to the last primary key column to read data whose primary key values are in the specified range. For example, the primary key of a data table consists of the following primary key columns: PK1, PK2, and PK3. When data is read, Tablestore first determines whether the PK1 value of a row is in the range that is specified for the first primary key column. If the PK1 value of a row is in the range, Tablestore stops determining whether the values of other primary key columns of the row are in the ranges that are specified for each primary key column and returns the row. If the PK1 value of a row is not in the range, Tablestore continues to determine whether the values of other primary key columns of the row are in the ranges that are specified for each primary key column in the same manner as PK1.

If one of the following conditions is met, the GetRange operation may stop and return data:

• The amount of scanned data reaches 4 MB.

• The number of scanned rows reaches 5,000.

• The number of returned rows reaches the upper limit.

• The read throughput is insufficient to read the next row of data because all reserved read throughput is consumed.

API operation

// Query multiple rows of data whose primary key values are in the specified range in a table. 
// @param GetRangeRequest            Encapsulate the parameters required to call the GetRange operation. 
// @return GetRangeResponse          The content of the response to the GetRange operation. 
GetRange(request *GetRangeRequest) (*GetRangeResponse,error)                   

Parameters

Sample code

The following sample code provides an example on how to read data whose primary key values are in the specified range:

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")

To view the detailed sample code, visit GetRange@GitHub.