All Products
Search
Document Center

Tablestore:GetRow

Last Updated:Nov 09, 2023

Reads a single row of data based on the specified primary key.

Request syntax

message GetRowRequest {
    required string table_name = 1;
    required bytes primary_key = 2; // The data is encoded as binary data in the PlainBuffer format. 
    repeated string columns_to_get = 3; // If you do not specify this parameter, all columns are read. 
    optional TimeRange time_range = 4;
    optional int32 max_versions = 5;
    optional bytes filter = 7;
    optional string start_column = 8;
    optional string end_column = 9;
    optional bytes token = 10;
}

Parameter

Type

Required

Description

table_name

string

Yes

The name of the table whose data you want to read. For more information, see CU consumption.

primary_key

bytes

Yes

All primary key columns of the row, including the names and values of the primary key columns. The primary key columns are encoded in the PlainBuffer format. For more information about PlainBuffer, see PlainBuffer.

columns_to_get

string

No

The names of the columns that you want to return. If you do not specify this parameter, all columns of the row are returned. The value of this parameter can contain up to 128 strings.

If the specified column does not exist, data of the specified column is not returned. If you specify duplicate column names, the response includes this column only once.

time_range

TimeRange

No (You must specify at least one of time_range and max_versions.)

The timestamp range in which you want to read multiple versions of data. The unit is millisecond. The minimum value of the timestamp is 0, and the maximum value is INT64.MAX.

If you want to query data within a specified time range, specify start_time and end_time. If you want to query data that contains a specified timestamp, specify specific_time.

If the value of time_range is [100, 200), only the columns whose timestamp is within the range of [100, 200) are returned.

max_versions

int32

No (You must specify at least one of time_range and max_versions.)

The maximum number of versions of data that you want to return.

If the value of max_versions is 2, up to two versions of data is returned for each column.

filter

bytes

No

The expression of the filter condition. The expression of the filter condition is serialized as binary data by using Protobuf. For more information, see Filter.

start_column

string

No

The column from which the read operation starts in the row. This parameter is used to read wide columns. The columns are sorted based on their names in alphabetical order. The response contains the specified start column.

If a table contains columns a, b, and c, and the value of start_column is b, the read operation starts from column b, and columns b and c are returned.

end_column

string

No

The response does not contain the specified end column. The columns are sorted based on their names in alphabetical order.

Example: If a table contains columns a, b, and c, and the value of end_column is b, the read operation ends at column b, and only column a is returned.

token

bytes

No

The position at which the next read operation starts in the wide column. This parameter is unavailable.

Response syntax

message GetRowResponse {
    required ConsumedCapacity consumed = 1;
    required bytes row = 2; // The data is encoded as binary data in the PlainBuffer format.
}

Parameter

Type

Description

consumed

ConsumedCapacity

The number of capacity units (CUs) consumed by this request.

row

bytes

The data that is read from the row. If the requested row does not exist, no data is returned.

The returned data is encoded in the PlainBuffer format. For more information about PlainBuffer, see PlainBuffer.

Use Tablestore SDKs

You can use the following Tablestore SDKs to read a row of data:

CU consumption

  • If the requested row does not exist, one read CU is consumed.

  • If the requested row exists, the number of consumed read CUs is rounded up from the value that is calculated by using the following formula: Number of consumed read CUs = (Size of data in all primary key columns of the row + Size of data in the attribute columns that are read)/4 KB. For more information about how to calculate the data size, see Billing overview.

  • If the request times out and the results are undefined, CUs may or may not be consumed.

  • If an HTTP status code 5xx is returned, which indicates that an internal error occurred, the operation does not consume CUs. If other errors are returned, one read CU is consumed.