Read a single row of data - Tablestore - Alibaba Cloud Documentation Center

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;
    optional string transaction_id = 11;
}

Parameter	Type	Required	Description
table_name	string	Yes	The name of the table whose data you want to read.
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, 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 minimum value is 0, and the maximum value is INT64.MAX. Unit: milliseconds. 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. For example, if the value of time_range is [100, 200), the timestamp of the data in the returned columns must be within the range of [100, 200).
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 returned. 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 column at which the read operation ends. 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.
transaction_id	string	No	The ID of the local transaction. This parameter is required if you use the local transaction feature to read data.

Response syntax

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

Parameter	Type	Description
consumed	ConsumedCapacity	The number of capacity units (CUs) that are consumed by the operation. For more information, see CU consumption.
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.
next_token	bytes	The token that is returned if the number of columns in a row of data exceeds 128 in a read request.

Use Tablestore SDKs

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

Tablestore SDK for Java: Read a single row of data
Tablestore SDK for Go: Read a single row of data
Tablestore SDK for Python: Read a single row of data
Tablestore SDK for Node.js: Read a single row of data
Tablestore SDK for .NET: Read a single row of data
Tablestore SDK for PHP: Read a single 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.