Reads data whose primary keys are within a specified range.

Request syntax

message GetRangeRequest {
    required string table_name = 1;
    required Direction direction = 2;
    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 int32 limit = 6;
    required bytes inclusive_start_primary_key = 7; // The primary key is encoded as binary data in the PlainBuffer format. 
    required bytes exclusive_end_primary_key = 8; // The primary key is encoded as binary data in the PlainBuffer format. 
    optional bytes filter = 10;
    optional string start_column = 11;
    optional string end_column = 12;
}
Parameter Type Required Description
table_name string Yes The name of the table from which you want to read data.
direction Direction Yes The order in which you want to sort the rows in the response.
  • If you set this parameter to FORWARD, the value of the inclusive_start_primary parameter must be smaller than the value of the exclusive_end_primary parameter, and the rows in the response are sorted in ascending order of primary key values.
  • If you set of this parameter to BACKWARD, the value of the inclusive_start_primary parameter must be greater than the value of the exclusive_end_primary parameter, and the rows in the response are sorted in descending order of primary key values.
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 rows that meet the query conditions are returned. The value of this parameter can contain up to 128 strings.

If duplicate column names exist, the response includes the column only once.

time_range TimeRange No (Either max_versions or time_range is required) The timestamp range of data that you want to read. The unit is millisecond. Valid values: 0 to INT64.MAX.

If you want to query the data within a specified timestamp range, specify start_time and end_time. If you want to query the data with a specified timestamp, specify specific_time.

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 (Either max_versions or time_range is required) 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.

limit int32 No The maximum number of rows that you want to return. If the number of rows that meet the query conditions exceeds the value of this parameter, the response contains a breakpoint that records the position at which the read operation ends. The next read operation starts from this position. The value of this parameter must be greater than 0.

Tablestore returns up to 5,000 rows of data regardless of whether you specify this parameter. The total size of returned rows cannot exceed 4 MB.

inclusive_start_primary_key bytes Yes The primary key from which the read operation starts. The start primary key is encoded in the PlainBuffer format. For more information about PlainBuffer, see PlainBuffer.

If the primary key of a row in the table from which you want to read data is the same as the start primary key, the row is included in the response.

exclusive_end_primary_key bytes Yes The primary key at which the read operation ends. The end primary key is encoded in the PlainBuffer format. For more information about PlainBuffer, see PlainBuffer.

If the primary key of a row is the same as the end primary key, the row is not included in the response regardless of whether the row is in the table from which you want to read data.

For the GetRange operation, the primary key columns in the values of inclusive_start_primary_key and exclusive_end_primary_key can be one of the following types dedicated to this operation: INF_MIN and INF_MAX. If the type of a primary key column in the start primary key or end primary key is INF_MIN, the value of the column in the start primary key or end primary key is smaller than the value of the column in other primary keys. If the type of a primary key column in the start primary key or end primary key is INF_MAX, the value of the column in the start primary key or end primary key is greater than the value of the column in other primary keys.

filter bytes No The expression of the filter condition, which 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 a row. This parameter is used to read wide columns. The response contains the specified start column. The columns are sorted based on their names in alphabetical order.

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 in a row. This parameter is used to read wide columns. The response does not contain the specified end column. The columns are sorted based on their names in alphabetical order.

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.

Response syntax

message GetRangeResponse {
    required ConsumedCapacity consumed = 1;
    required bytes rows = 2; 
    optional bytes next_start_primary_key = 3; 
}
Parameter Type Description
consumed ConsumedCapacity The number of capacity units (CUs) that are consumed by the operation. For more information, see CU consumption.
rows bytes The rows that are returned by the operation. The rows are encoded in the PlainBuffer format. For more information, see PlainBuffer.

If direction in the request is set to FORWARD, the rows in the response are sorted in ascending order of primary key values. If direction in the request is set to BACKWARD, the rows in the response are sorted in descending order of primary key values.

The primary key columns and attribute columns for each row in the response contain only the columns that you specified for columns_to_get in the request. The order of the columns for columns_to_get in the response may be different from the order of the columns that you specified for columns_to_get in the request. The order of the primary key columns in the response may be different from the order of the primary key columns when the table is created.

If the value of the columns_to_get parameter in the request does not contain a primary key column, rows that do not contain one or more attribute columns specified in columns_to_get are not included in the response even if the primary keys of the rows are within the query range.

next_start_primary_key bytes The breakpoint that records the position at which the read operation ends. The breakpoint is encoded in the PlainBuffer format. For more information, see PlainBuffer.

If this parameter is left empty, the GetRange operation returns all rows that meet the query conditions.

If this parameter is not left empty, the GetRange operation returns only the data within the range of [inclusive_start_primary_key, next_start_primary_key). If you want to obtain the remaining data, set inclusive_start_primary_key to the value of next_start_primary_key and retain the value of exclusive_end_primary_key in the original request to call the GetRange operation again.
Note The GetRange operation can return up to 5,000 rows upon each request. The total size of the data in the rows cannot exceed 4 MB. The response to a GetRange request may contain a value of the next_start_primary_key parameter even if you do not specify a limit in the request. When you call the GetRange operation, you must check whether the response contains the next_start_primary_key parameter.

Use Tablestore SDKs

You can use the following Tablestore SDKs to read data whose primary keys are within a specified range:

CU consumption

  • The number of read CUs that are consumed for the GetRange operation is rounded up from the calculation result of the following formula: Number of consumed read CUs = (Size of the data in all primary key columns of the rows that meet the query conditions + Size of the 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.