All Products
Search

This Product

    Tablestore:read a single row of data

    Document Center

    Tablestore:read a single row of data

    Last Updated:Jun 22, 2026

    Use the PHP SDK to read a single row of data from a Tablestore table by specifying its primary key.

    Usage notes

    When reading data, provide the complete primary key value, including the auto-increment primary key column value.

    Before you begin

    Initialize the Tablestore Client

    Method description

    public function getRow(array $request)

    Description of the $request parameter

    Name

    Type

    Description

    table_name (Required)

    string

    The name of the data table.

    primary_key (Required)

    array

    The primary key of the row, including column names and values.

    • Supported primary key column data types: STRING, INTEGER, and BINARY.

    • The number and types of primary key columns must match those defined in the data table.

    max_versions (Optional)

    int

    The maximum number of versions to return.

    • You must set either max_versions or time_range.

    • If the number of matching versions exceeds this value, versions are returned from newest to oldest up to the specified limit.

    time_range (Optional)

    array

    The version range of data to read.

    • You must set either max_versions or time_range.

    • Each attribute column can contain multiple versions. Only versions within the specified range are returned.

    columns_to_get (Optional)

    array

    The columns to read. You can specify both primary key columns and attribute columns.

    • If not set, the entire row is returned.

    • If set but the row contains none of the specified columns, null is returned.

    column_filter (Optional)

    array

    The filter condition to apply. For more information, see Filter.

    • If both columns_to_get and column_filter are set, Tablestore first retrieves the specified columns, then applies the filter to the results.

    transaction_id (Optional)

    string

    The ID of the local transaction. For more information, see Local transactions.

    Sample code

    The following example reads a row whose primary key value is row1.

    $request = array (
    'table_name' => 'test_table',
    // Construct primary key
    'primary_key' => array (
        array ('id', 'row1')
    ),
    'max_versions' => 1
);

try {
    // Call the getRow method to read row data
    $response = $client->getRow ($request);
    echo "* Read CU Cost: " . $response['consumed']['capacity_unit']['read'] . "\n";
    echo "* Write CU Cost: " . $response['consumed']['capacity_unit']['write'] . "\n";
    echo "* Row Data: " . "\n";
    echo "Primary Key: ". json_encode($response['primary_key']) . "\n";
    echo "Attribute Columns: ". json_encode($response['attribute_columns']) . "\n";
} catch (Exception $e){
    echo "Get Row failed.";
}

    • Set a version range to return only data within that range.

      // Set the query data 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');

    References