Tablestore PHP SDK Range Read Data - Tablestore - Alibaba Cloud Documentation Center

Use the Tablestore PHP SDK to read rows within a specified primary key range.

Prerequisites

Method

public function getRange(array $request)

The following table describes the $request parameters.

Name	Type	Description
table_name (required)	string	The name of the data table.
inclusive_start_primary_key (required)	array	The start primary key. Includes primary key column names and values. The response includes the start primary key. The number and types of primary keys must match those of the data table. For forward reads, the start primary key must be less than the end primary key. For backward reads, the start primary key must be greater than the end primary key. PrimaryKeyTypeConst::CONST_INF_MIN means negative infinity. PrimaryKeyTypeConst::CONST_INF_MAX means positive infinity.
exclusive_end_primary_key (required)	array	The end primary key. Includes primary key column names and values. The response excludes the end primary key. The number and types of primary keys must match those of the data table. PrimaryKeyTypeConst::CONST_INF_MIN means negative infinity. PrimaryKeyTypeConst::CONST_INF_MAX means positive infinity.
direction (required)	string	The read direction. DirectionConst::CONST_FORWARD: Forward read. DirectionConst::CONST_BACKWARD: Backward read.
max_versions (optional)	int	The maximum number of versions. Set either max_versions or time_range. If the number of matching versions exceeds max_versions, the response returns the most recent versions up to max_versions.
time_range (optional)	array	The version range. Set either max_versions or time_range. Each attribute column in a Tablestore data table can have different versions. When you set time_range, only data within that range is returned.
limit (optional)	int	The maximum number of rows to return per request. Must be greater than 0. If more rows match the query, the response returns the specified number of rows and a start primary key for the next request.
columns_to_get (optional)	array	The columns to read. Can be primary key columns or attribute columns. If not set, the response returns full rows. If set and a row contains none of the specified columns, the response returns null for that row.
column_filter (optional)	array	The filter condition. For more information, see Filters. If both columns_to_get and column_filter are set, Tablestore first applies columns_to_get, then applies column_filter.

Examples

The following example reads data from the test_table table where the primary key value is greater than row1.

$request = array (
    'table_name' => 'test_table',
    // Set the start primary key
    'inclusive_start_primary_key' => array (
        array('id', 'row1')
    ),
    // Set the end primary key (the response excludes this key)
    'exclusive_end_primary_key'  => array (
        array('id', null, PrimaryKeyTypeConst::CONST_INF_MAX)
    ),
    // Set forward read
    'direction' => DirectionConst::CONST_FORWARD,
    // Set the number of versions to read
    'max_versions' => 1
);

try {
    // Call getRange to read rows
    $response = $client->getRange ($request);

    // Process the response
    echo "* Read CU Cost: " . $response['consumed']['capacity_unit']['read'] . "\n";
    echo "* Write CU Cost: " . $response['consumed']['capacity_unit']['write'] . "\n";
    echo "* Row Data: " . "\n";
    foreach ($response['rows'] as $row) {
        echo json_encode($row) . "\n";
    }
} catch (Exception $e){
    echo "Get Range failed.";
}

A single range scan returns up to 5,000 rows or 4 MB. If the result exceeds these limits, the response includes a start primary key for the next request. Use the following code to perform iterative queries.

while (true) {
    // Call getRange to read rows
    $response = $client->getRange ($request);
    // Process the response
    echo "* Read CU Cost: " . $response['consumed']['capacity_unit']['read'] . "\n";
    echo "* Write CU Cost: " . $response['consumed']['capacity_unit']['write'] . "\n";
    echo "* Row Data: " . "\n";
    foreach ($response['rows'] as $row) {
        echo json_encode($row) . "\n";
    }
    
    if ($response['next_start_primary_key'] != null){
        $request['inclusive_start_primary_key'] = $response['next_start_primary_key'];
    } else {
        break;
    }
}

Configure the following optional settings as needed.

Set the read direction to reverse.

$request = array (
    'table_name' => 'test_table',
    // Set the start primary key (for backward reads, the start key must be greater than the end key)
    'inclusive_start_primary_key' => array (
        array('id', null, PrimaryKeyTypeConst::CONST_INF_MAX)
    ),
    // Set the end primary key (the response excludes this key)
    'exclusive_end_primary_key'  => array (
        array('id', 'row1')
    ),
    // Set backward read
    'direction' => DirectionConst::CONST_BACKWARD,
    // Set the number of versions to read
    'max_versions' => 1
);

Set a version range. Only data within the specified range is returned.

// Set the version range to one day before the current time
$request['time_range'] = array (
    'start_time' => intval(microtime(true) * 1000) - 86400 * 1000,
    'end_time' => intval(microtime(true) * 1000)
);

Specify the attribute columns to read.

$request['columns_to_get'] = array('col2');

Set the maximum number of rows to return per request.
```
$request['limit'] = 10;
```

References

Batch read data