All Products
Search

This Product

    Tablestore:read a single row of data

    Document Center

    Tablestore:read a single row of data

    Last Updated:Mar 11, 2026

    Read a single row from a Tablestore table by primary key, using the PHP SDK.

    Usage notes

    Provide the complete primary key value when reading data, including the value for the auto-increment primary key column.

    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 information, including column names and values.

    • Primary key column data types include STRING, INTEGER, and BINARY.

    • The number and types of primary keys must match those of the data table.

    max_versions (Optional)

    int

    The maximum number of data versions to return.

    • Set either max_versions or time_range.

    • If matching data versions exceed this value, the system returns versions from newest to oldest up to the specified limit.

    time_range (Optional)

    array

    The data version range.

    • Set either max_versions or time_range.

    • Each attribute column in a Tablestore table can contain multiple data versions. Only data within the specified version range is returned.

    columns_to_get (Optional)

    array

    The data columns to read. Accepts 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. For more information, see Filter.

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

    transaction_id (Optional)

    string

    The local transaction ID that uniquely identifies a local transaction. For more information, see Local transactions.

    Sample code

    The following example reads a single row with the primary key value 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