You can call this operation to read data whose primary keys are within a specified range.
Request structure
message GetRangeRequest {
required string table_name = 1;
required Direction direction = 2;
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 int32 limit = 6;
required bytes inclusive_start_primary_key = 7; // Encode the parameter value in the PlainBuffer format to obtain binary data.
required bytes exclusive_end_primary_key = 8; // Encode the parameter value in the PlainBuffer format to obtain binary data.
optional bytes filter = 10;
optional string start_column = 11;
optional string end_column = 12;
}
Parameter | Type | Required | Description |
---|---|---|---|
table_name | string | Yes |
This parameter specifies the name of the table that contains the data to read. |
direction | Direction | Yes |
This parameter specifies the query direction.
|
columns_to_get | repeated string | No |
|
time_range | TimeRange | Either max_versions or time_range is required |
Example: If the value of time_range is (100, 200), the timestamp of the returned column data must be within the range of [100, 200). |
max_versions | int32 | Either max_versions or time_range is required |
This parameter specifies 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. |
limit | int32 | No |
|
inclusive_start_primary_key | bytes | Yes |
This parameter specifies a start primary key. The read starts from the row that contains the start primary key. If the row exists, the response contains this row. It is encoded in Plainbuffer. For more information, see Plainbuffer. |
exclusive_end_primary_key | bytes | Yes |
|
filter | bytes | No |
|
start_column | string | No |
Example: A table contains columns a, b, and c. If the value of start_column is b, the reading starts from column b, and columns b and c are returned. |
end_column | string | No |
Example: A table contains columns a, b, and c. If the value of end_column is b, the reading ends at column b, and column a is returned. |
Response structure
message GetRangeResponse {
required ConsumedCapacity consumed = 1;
required bytes rows = 2;
optional bytes next_start_primary_key = 3;
}
Parameter | Type | Description |
---|---|---|
consumed | ConsumedCapacity |
This parameter specifies the number of capacity units (CUs) consumed by this operation. |
rows | bytes |
|
next_start_primary_key | bytes |
|
CU consumption
-
The number of read CUs consumed by the GetRange operation is calculated based on the following formula: Number of read CUs consumed by the GetRange operation = [(Size of primary key columns of the row within the query range + Size of actually read attribute columns)/4 KB] rounded up. For more information about how to calculate the data size, see pricing.
-
If the request times out and the results are undefined, CUs may or may not be consumed.
-
If an internal error is returned (HTTP status code: 5xx), this operation does not consume CUs. If other errors are returned, one read CU is consumed.