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:

  • Tablestore SDK for Java: GetRow
  • Tablestore SDK for Go: GetRow
  • Tablestore SDK for Python: GetRow
  • Tablestore SDK for Node.js: GetRow
  • Tablestore SDK for .NET: GetRow
  • Tablestore SDK for PHP: GetRow

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.