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 primary key columns are encoded as binary data in the PlainBuffer format. 
    repeated string columns_to_get = 3; // If this parameter is not specified, 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.
primary_key bytes Yes All the primary key columns of the specified row, including the primary key column names and values. The primary key columns are encoded in the PlainBuffer format. For more information about PlainBuffer, see PlainBuffer.
columns_to_get repeated string No The names of the columns to return.
  • If this parameter is not specified, all columns of the row are returned.
  • If the specified column does not exist, data in this column is not returned.
  • If two duplicate column names are specified, the response only includes this column once.
  • In columns_to_get, the number of strings cannot exceed 128.
time_range TimeRange Yes (At least one of time_range and max_versions is required.) The timestamp range of the data to read.
  • The minimum value is 0, and the maximum value is INT64.MAX.
  • To query the data within a time range, specify start_time and end_time.
  • To query the data with a specific timestamp, specify specific_time.

Example: If the value of time_range is [100, 200), the timestamp of the data in the returned column must be within the range of [100, 200).

max_versions int32 Yes (At least one of time_range and max_versions is required.)

The maximum number of versions of data to return.

Example: If the value of max_versions is 2, a maximum of 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 starts in the row. This parameter is used to read wide rows.

  • The response contains the specified start 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 start_column is b, the current read starts from column b, and columns b and c are returned.

end_column string No

  • The column at which the read ends in the row. This parameter is used to read wide rows.

  • 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 current read ends at column b, and only column a is returned.

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 CapacityUnit

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

row bytes

The data that is read from the row. The data is encoded in the PlainBuffer format. For more information about PlainBuffer, see PlainBuffer.

If the requested row does not exist, no data is returned.

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 calculated and rounded up based on the following formula: Number of consumed read CUs = [(Size of the data in all the primary key columns of the row + Size of the data in the attribute columns that are actually 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 internal error (HTTP status code: 5xx) is returned, this request does not consume CUs. If other errors are returned, one read CU is consumed.