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 | 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 | 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: 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.