GetRange - Tablestore - Alibaba Cloud Documentation Center

Reads data whose primary key values are within the 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 start primary key information is encoded as binary data in the PlainBuffer format. 
    required bytes exclusive_end_primary_key = 8; // The end primary key information 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.
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_key parameter must be smaller than the value of the exclusive_end_primary_key parameter, and the rows in the response are sorted in ascending order of primary key values. If you set this parameter to BACKWARD, the value of the inclusive_start_primary_key parameter must be greater than the value of the exclusive_end_primary_key parameter, and the rows in the response are sorted in descending order of primary key values.
columns_to_get	repeated string	No	The names of the columns that you want to return. The value of this parameter can contain up to 128 strings. If you do not specify this parameter, all columns of the rows that meet the query conditions are returned. If all columns of a row do not meet the query conditions, the row is not returned and the return value is null. If a row contains some of the columns that meet the query conditions, the row is returned and only the columns that meet the query conditions are included in the response. If duplicate column names exist, the response includes the column only once.
time_range	TimeRange	No. Only one of max_versions and time_range is required.	The timestamp range of data that you want to read. Valid values: 0 to `INT64.MAX`. Unit: millisecond. If you want to query the data within a timestamp range, specify start_time and end_time. The value of time_range is a left-closed, right-open interval. Example: `[start_time, end_time)`. If you set this parameter to `[100, 200)`, the timestamp of the data in the returned columns must be within the range of `[100, 200)`. If you want to query the data at a timestamp, specify specific_time.
max_versions	int32	No. Only one of max_versions and time_range is required.	The maximum number of versions of data that you want to return. For example, if the value of max_versions is 2, a maximum of two versions of data are returned for each column.
limit	int32	No	The maximum number of rows that you want to return. The value of this parameter must be greater than 0. 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. 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 information from which the read operation starts. The start primary key information is encoded in the PlainBuffer format. For more information, see PlainBuffer. If a row contains the start primary key column, the row is included in the response.
exclusive_end_primary_key	bytes	Yes	The primary key information at which the read operation ends. The end primary key information is encoded in the PlainBuffer format. For more information, see PlainBuffer. If a row contains the end primary key column, the row is excluded from the response. 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. INF_MIN indicates an infinitely small value. If the type of a primary key column is INF_MIN, the values of the column are smaller than the values of other columns. INF_MAX indicates an infinitely great value. If the type of a primary key column is INF_MAX, the values of the column are greater than the values of other columns.
filter	bytes	No	The expressions of filter conditions. The expressions of filter conditions are 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 for wide-column read. The response includes 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 for wide-column read. The response excludes 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 include only the columns that you specified for columns_to_get in the request. The order of the columns 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 specified when the table is created. If the value of columns_to_get in the request does not contain a primary key column, rows that do not contain attribute columns specified in columns_to_get are excluded from the response even if the primary key values 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 the return value is empty, the GetRange operation returns all data that meets the query conditions. If the return value is not 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 next_start_primary_key even if you do not specify a limit in the request. When you call the GetRange operation, you must check whether the response contains next_start_primary_key.

Use Tablestore SDKs

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

Tablestore SDK for Java: Read data whose primary key values are in the specified range
Tablestore SDK for Go: Read data whose primary key values are in the specified range
Tablestore SDK for Python: Read data whose primary key values are in the specified range
Tablestore SDK for Node.js: Read data whose primary key values are in the specified range
Tablestore SDK for .NET: Read data whose primary key values are in the specified range
Tablestore SDK for PHP: Read data whose primary key values are in the 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 Storage usage.
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.