全部產品
Search
文件中心

Tablestore:讀取資料

更新時間:Jun 30, 2024

Tablestore提供了GetRow介面用於讀取單行資料以及BatchGetRow、GetRange等介面用於讀取多行資料。

查詢方式

Tablestore提供的資料讀取介面包括GetRow、BatchGetRow和GetRange。讀取資料時,請根據實際查詢情境使用相應查詢方式讀取資料。

重要

當要讀取帶有自增主鍵列的表資料時,請確保已擷取到包含自增主鍵列值在內的完整主鍵。更多資訊,請參見主鍵列自增。如果未記錄自增主鍵列的值,您可以使用範圍讀取資料按照第一個主鍵列確定範圍讀取資料。

查詢方式

說明

適用情境

讀取單行資料

調用GetRow介面讀取一行資料。

適用於能確定完整主鍵且要讀取行數較少的情境。

批量讀取資料

調用BatchGetRow介面一次請求讀取多行資料或者一次對多張表進行讀取。

BatchGetRow操作由多個GetRow子操作組成,構造子操作的過程與使用GetRow介面時相同。

適用於能確定完整主鍵,且要讀取行數較多或者要讀取多個表中資料的情境。

範圍讀取資料

調用GetRange介面讀取一個範圍內的資料。

GetRange操作支援按照確定範圍進行正序讀取和逆序讀取,可以設定要讀取的行數。如果範圍較大,已掃描的行數或者資料量超過一定限制,會停止掃描,並返回已擷取的行和下一個主鍵資訊。您可以根據返回的下一個主鍵資訊,繼續發起請求,擷取範圍內剩餘的行。

適用於能確定完整主鍵範圍或者主鍵首碼的情境。

重要

如果不能確定主鍵首碼,您也可以通過設定完整主鍵範圍均為虛擬點INF_MIN和INF_MAX進行全表資料掃描,但是執行此操作會消耗較多計算資源,請謹慎使用。

前提條件

  • 已初始化Client,詳情請參見初始化OTSClient

  • 已建立資料表並寫入資料。

讀取單行資料

調用GetRow介面讀取一行資料。讀取的結果可能有如下兩種:

  • 如果該行存在,則返回該行的各主鍵列以及屬性列。

  • 如果該行不存在,則返回中不包含行,並且不會報錯。

介面

/**
 * 讀取一行資料。
 * @api
 * @param [] $request 請求參數。
 * @return [] 請求返回。 
 * @throws OTSClientException 當參數檢查出錯或服務端返回校正出錯時拋出異常。
 * @throws OTSServerException 當OTS服務端返回錯誤時拋出異常。
 */
public function getRow(array $request);            

請求參數

參數

說明

table_name

資料表名稱。

primary_key

行的主鍵。主鍵包括主鍵列名、主鍵類型和主索引值。

重要

設定的主鍵個數和類型必須和資料表的主鍵個數和類型一致。

max_versions

最多讀取的版本數。

重要

max_versions與time_range必須至少設定一個。

  • 如果僅設定max_versions,則最多返回所有版本中從新到舊指定數量版本的資料。

  • 如果僅設定time_range,則返回該範圍內所有資料或指定版本資料。

  • 如果同時設定max_versions和time_range,則最多返回版本號碼範圍內從新到舊指定數量版本的資料。

time_range

讀取版本號碼範圍或特定版本號碼的資料。更多資訊,請參見TimeRange

重要

max_versions與time_range必須至少設定一個。

  • 如果僅設定max_versions,則最多返回所有版本中從新到舊指定數量版本的資料。

  • 如果僅設定time_range,則返回該範圍內所有資料或指定版本資料。

  • 如果同時設定max_versions和time_range,則最多返回版本號碼範圍內從新到舊指定數量版本的資料。

  • 如果要查詢一個範圍的資料,則需要設定start_time和end_time。start_time和end_time分別表示起始時間戳記和結束時間戳記,範圍為前閉後開區間,即[start_time, end_time)

  • 如果要查詢特定版本號碼的資料,則需要設定specific_time。specific_time表示特定的時間戳記。

specific_time和[start_time, end_time)中只需要設定一個。

時間戳記的單位為毫秒,最小值為0,最大值為INT64.MAX

columns_to_get

讀取的列集合,列名可以是主鍵列或屬性列。

  • 如果不設定返回的列名,則返回整行資料。

  • 如果設定了返回的列名,當某行中指定的列均不存在時,則不返回該行,即傳回值為null;當某行中存在部分指定的列時,則返回該行且只返回存在的列。

說明
  • 查詢一行資料時,預設返回此行所有列的資料。如果需要只返回特定列,可以通過設定columns_to_get參數限制。如果將col0和col1加入到columns_to_get中,則只返回col0和col1列的值。

  • 當columns_to_get和column_filter同時使用時,執行順序是先擷取columns_to_get指定的列,再在返回的列中進行條件過濾。

start_column

讀取的起始列,主要用於寬行讀,返回的結果中包含當前起始列。

列的順序按照列名的字典序排序。例如一張表有“a”、“b”、“c”三列,讀取時設定start_column為“b”,則會從“b”列開始讀,返回“b”、“c”兩列。

end_column

讀取時的結束列,主要用於寬行讀,返回的結果中不包含當前結束列。

列的順序按照列名的字典序排序。例如一張表有“a”、“b”、“c”三列,讀取時指定end_column為“b”,則讀到“b”列時會結束,返回“a”列。

token

寬行讀取時下一次讀取的起始位置,暫不可用。

column_filter

使用過濾器,在服務端對讀取結果再進行一次過濾,只返回符合過濾器中條件的資料行。更多資訊,請參見過濾器

說明

當columns_to_get和column_filter同時使用時,執行順序是先擷取columns_to_get指定的列,再在返回的列中進行條件過濾。

請求格式

$result = $client->getRow([
    'table_name' => '<string>',                     //設定資料表名稱。
    'primary_key' => [                              //設定主鍵。
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'max_versions' => <integer>,
    'time_range' => [
        'start_time' => <integer>,
        'end_time' => <integer>,
        'specific_time' => <integer>
    ],
    'start_column' => '<string>',
    'end_column' => '<string>',
    'token' => '<string>',
    'columns_to_get' => [
        '<string>',
        '<string>',
        //...   
    ],
    'column_filter' =>  <ColumnCondition>
]);            

響應參數

參數

說明

consumed

本次操作消耗服務能力單元的值。

capacity_unit表示使用的讀寫能力單元。

  • read:讀輸送量

  • write:寫輸送量

primary_key

主鍵的值,和請求時一致。

說明

如果該行不存在,則primary_key為空白列表[]。

attribute_columns

屬性列的值。

說明

如果該行不存在,則attribute_columns為空白列表[]。

  • 每一項的順序是屬性名稱、屬性值ColumnValue、屬性類型ColumnType、時間戳記。

    時間戳記為64位整數,用於表示屬性列資料的多個不同的版本。

  • 返回結果中的屬性會按照屬性名稱的字典序升序,屬性的多個版本按時間戳記降序。

  • 其順序不保證與請求中的columns_to_get一致。

next_token

寬行讀取時下一次讀取的位置,暫不可用。

結果格式

[
    'consumed' => [
        'capacity_unit' => [
            'read' => <integer>,
            'write' => <integer>
        ]
    ],
    'primary_key' => [ 
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ],  
    'attribute_columns' => [
            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
    ],
    'next_token' => '<string>'
]            

樣本

讀取最新版本資料和指定列

以下樣本用於讀取一行資料,設定讀取最新版本的資料和讀取的列。

$request = [
    'table_name' => 'MyTable',
    'primary_key' => [ //設定主鍵。
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'max_versions' => 1,                     //設定讀取最新版本。
    'columns_to_get' => ['Col0']             //設定讀取的列。
];
$response = $otsClient->getRow ($request);            

使用過濾器讀取資料

以下樣本用於在讀取一行資料時使用過濾器。

$request = [
    'table_name' => 'MyTable',
    'primary_key' => [ //設定主鍵。
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'max_versions' => 1,                     //設定讀取最新版本。
    'column_filter' => [                     //設定過濾器,當Col0列的值為0時,返回該行。
        'column_name' => 'Col0',
        'value' => 0,
        'comparator' => ComparatorTypeConst::CONST_EQUAL,
        'pass_if_missing' => false          //如果Col0列不存在,則不返回該行。
    ]
];
$response = $otsClient->getRow ($request);            

批量讀取資料

調用BatchGetRow介面一次請求讀取多行資料,也支援一次對多張表進行讀取。BatchGetRow由多個GetRow子操作組成。構造子操作的過程與使用GetRow介面時相同。

BatchGetRow的各個子操作獨立執行,Tablestore會分別返回各個子操作的執行結果。

注意事項

  • 由於批量讀取可能存在部分行失敗的情況,失敗行的錯誤資訊在返回的BatchGetRowResponse中,但並不拋出異常。因此調用BatchGetRow介面時,需要檢查傳回值,判斷每行的狀態是否成功。

  • 批量讀取的所有行採用相同的參數條件,例如ColumnsToGet=[colA],表示要讀取的所有行都唯讀取colA列。

  • BatchGetRow操作單次支援讀取的最大行數為100行。

介面

/**
 * 讀取指定的多行資料。
 * 請注意BatchGetRow在部分行讀取失敗時,會在返回的$response中表示,而不是拋出異常。更多資訊,請參見處理BatchGetRow的返回範例。
 * @api
 * @param [] $request 請求參數。
 * @return [] 請求返回。
 * @throws OTSClientException 當參數檢查出錯或服務端返回校正出錯時。
 * @throws OTSServerException 當OTS服務端返回錯誤時。
 */
public function batchGetRow(array $request);  
            

請求參數

BatchGetRow和GetRow的區別如下:

  • 增加了資料表的層級結構,可以一次讀取多個資料表的資料。

    tables以資料表為單位組織,後續為各個資料表的操作,設定了需要讀取的行資訊。

  • primary_key變為primary_keys,支援設定多行的主鍵,可以一次讀取多行資料。

請求格式

$result = $client->batchGetRow([
    'tables' => [                                            //設定資料表的層級結構。
        [
            'table_name' => '<string>',                      //設定資料表名稱。
            'primary_keys' => [                              //設定主鍵。
                [
                    ['<string>', <PrimaryKeyValue>], 
                    ['<string>', <PrimaryKeyValue>],
                    ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
                ], 
                //其他主鍵。
            ]
            'max_versions' => <integer>,
            'time_range' => [
                'start_time' => <integer>,
                'end_time' => <integer>,
                'specific_time' => <integer>
            ],
            'start_column' => '<string>',
            'end_column' => '<string>',
            'token' => '<string>',
            'columns_to_get' => [
                '<string>',
                '<string>',
                //...   
            ],
            'column_filter' =>  <ColumnCondition>
        ],
        //其他資料表。
    ]
]);            

響應參數

tables以table為單位組織,和請求一一對應, 參數說明請參見下表。

參數

說明

table_name

資料表名稱。

is_ok

該行操作是否成功。

  • 如果值為true,則該行讀取成功,此時error無效。

  • 如果值為false,則該行讀取失敗,此時consumed、primary_key、attribute_columns無效。

error

用於在操作失敗時的響應訊息中表示錯誤資訊。

  • code表示當前單行操作的錯誤碼。

  • message表示當前單行操作的錯誤資訊。

consumed

本次操作消耗服務能力單元的值。

capacity_unit表示使用的讀寫能力單元。

  • read:讀輸送量

  • write:寫輸送量

primary_key

主鍵的值,和請求時一致。

說明

如果該行不存在,則primary_key為空白列表[]。

attribute_columns

屬性列的值。

說明

如果該行不存在,則attribute_columns為空白列表[]。

  • 每一項的順序是屬性名稱、屬性值ColumnValue、屬性類型ColumnType、時間戳記。

    時間戳記為64位整數,用於表示屬性列資料的多個不同的版本。

  • 返回結果中的屬性會按照屬性名稱的字典序升序,屬性的多個版本按時間戳記降序。

  • 其順序不保證與請求中的columns_to_get一致。

next_token

寬行讀取時下一次讀取的位置,暫不可用。

結果格式

[
    'tables' => [
        [
            'table_name' => '<string>',
            'rows' => [
                [
                    'is_ok' => true || false,
                    'error' => [
                        'code' => '<string>',
                        'message' => '<string>',
                    ]
                    'consumed' => [
                        'capacity_unit' => [
                            'read' => <integer>,
                            'write' => <integer>
                        ]
                    ],
                    'primary_key' => [ 
                        ['<string>', <PrimaryKeyValue>], 
                        ['<string>', <PrimaryKeyValue>],
                        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
                    ],  
                    'attribute_columns' => [
                            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                    ],
                    'next_token' => '<string>'
                ],
                //其他行。
            ]
        ],
        //其他資料表。
    ]
]            

樣本

以下樣本用於批量一次讀取30行,分別從3個資料表中讀取資料,每個資料表讀取10行。

//從3個資料表中讀取資料,每個資料表讀取10行。
$tables = array();
for($i = 0; $i < 3; $i++) {
    $primary_keys = array();
    for($j = 0; $j < 10; $j++) {
        $primary_keys[] = [
            ['pk0', $i],
            ['pk1', $j]
        ];
    }
    $tables[] = [
        'table_name' => 'SampleTable' . $i,
        'max_versions' => 1,
        'primary_keys' => $primary_keys
    ];
}
$request = [
    'tables' => $tables
];
$response = $otsClient->batchGetRow ($request);

//處理返回的每個資料表。
foreach ($response['tables'] as $tableData) {
  print "Handling table {$tableData['table_name']} ...\n";

  //處理該資料表下的每行資料。
  foreach ($tableData['rows'] as $rowData) {

    if ($rowData['is_ok']) {

      //處理讀取到的資料。
        $row = json_encode($rowData['primary_key']);
        print "Handling row: {$row}\n";

    } else {

      //處理出錯。
      print "Error: {$rowData['error']['code']} {$rowData['error']['message']}\n";
    }
  }
}            

詳細程式碼範例請參見下表。

樣本

說明

BatchGetRow1.php

展示了BatchGetRow擷取單個資料表多行的用法。

BatchGetRow2.php

展示了BatchGetRow擷取多個資料表多行的用法。

BatchGetRow3.php

展示了BatchGetRow擷取單個資料表多行同時指定擷取特定列的用法。

BatchGetRow4.php

展示了BatchGetRow處理返回結果的用法。

BatchGetRowWithColumnFilter.php

展示了BatchGetRow同時使用過濾器的用法。

範圍讀取資料

調用GetRange介面讀取一個範圍內的資料。

GetRange操作支援按照確定範圍進行正序讀取和逆序讀取,可以設定要讀取的行數。如果範圍較大,已掃描的行數或者資料量超過一定限制,會停止掃描,並返回已擷取的行和下一個主鍵資訊。您可以根據返回的下一個主鍵資訊,繼續發起請求,擷取範圍內剩餘的行。

說明

Tablestore表中的行都是按照主鍵排序的,而主鍵是由全部主鍵列按照順序組成的,所以不能理解為Tablestore會按照某列主鍵排序,這是常見的誤區。

注意事項

GetRange操作遵循最左匹配原則,讀取資料時,依次比較第一主鍵列到第四主鍵列。例如表的主鍵包括PK1、PK2、PK3三個主鍵列,讀取資料時,優先比較PK1是否在開始主鍵與結束主鍵的範圍內,如果PK1在設定的主鍵範圍內,則不會再比較其他的主鍵,返回在PK1主鍵範圍內的資料;如果PK1在設定的主鍵邊界上,則繼續比較PK2是否在開始主鍵與結束主鍵的範圍內,以此類推。

GetRange操作可能在如下情況停止執行並返回資料。

  • 掃描的行資料大小之和達到4 MB。

  • 掃描的行數等於5000。

  • 返回的行數等於最大返回行數。

  • 當前剩餘的預留讀輸送量已全部使用,餘量不足以讀取下一條資料。

當使用GetRange掃描的資料量較大時,Tablestore每次請求僅會掃描一次(行數大於5000或者大小大於4 MB停止掃描),超過限制的資料不會繼續返回,需要通過翻頁繼續擷取後面的資料。

介面

/**
 * 範圍讀起始主鍵和結束主鍵間的資料。
 * 請注意服務端可能會截斷此範圍,需要判斷返回中的next_start_primary_key來判斷是否繼續調用GetRange。
 * 可以指定最多讀取多少行。
 * 在指定開始主鍵和結束主鍵時,可以使用INF_MIN和INF_MAX分別表示最小值和最大值。更多資訊,請參見如下代碼範例。
 * @api
 * @param [] $request 請求參數。
 * @return [] 請求返回。
 * @throws OTSClientException 當參數檢查出錯或服務端返回校正出錯時。
 * @throws OTSServerException 當OTS服務端返回錯誤時。
 */
public function getRange(array $request);            

參數

GetRange和GetRow的區別如下:

  • primary_key變成inclusive_start_primary_key和exclusive_end_primary_key,範圍為前閉後開區間。

  • 增加direction表示讀取方向。

  • 增加limit限制返回行數。

參數

說明

table_name

資料表名稱。

inclusive_start_primary_key

本次範圍讀的起始主鍵和結束主鍵,起始主鍵和結束主鍵需要是有效主鍵或者是由INF_MIN和INF_MAX類型組成的虛擬點,虛擬點的列數必須與主鍵相同。

其中INF_MIN表示無限小,任何類型的值都比它大;INF_MAX表示無限大,任何類型的值都比它小。

  • inclusive_start_primary_key表示起始主鍵,如果該行存在,則返回結果中一定會包含此行。

  • exclusive_end_primary_key表示結束主鍵,無論該行是否存在,返回結果中都不會包含此行。

資料表中的行按主鍵從小到大排序,讀取範圍是一個左閉右開的區間,正序讀取時,返回的是大於等於起始主鍵且小於結束主鍵的所有的行。

exclusive_end_primary_key

direction

讀取方向。

  • 如果值為正序(DirectionConst::CONST_FORWARD),則起始主鍵必須小於結束主鍵,返回的行按照主鍵由小到大的順序進行排列。

  • 如果值為逆序(DirectionConst::CONST_BACKWARD),則起始主鍵必須大於結束主鍵,返回的行按照主鍵由大到小的順序進行排列。

假設同一表中有兩個主鍵A和B,A小於B。如果正序讀取[A, B),則按從A到B的順序返回主鍵大於等於A且小於B的行資料;如果逆序讀取[B, A),則按從B到A的順序返回大於A且小於等於B的行資料。

limit

資料的最大返回行數,此值必須大於0。

Tablestore按照正序或者逆序返回指定的最大返回行數後即結束該操作的執行,即使該區間內仍有未返回的資料。此時可以通過返回結果中的next_start_primary_key記錄本次讀取到的位置,用於下一次讀取。

max_versions

最多讀取的版本數。

重要

max_versions與time_range必須至少設定一個。

  • 如果僅設定max_versions,則最多返回所有版本中從新到舊指定數量版本的資料。

  • 如果僅設定time_range,則返回該範圍內所有資料或指定版本資料。

  • 如果同時設定max_versions和time_range,則最多返回版本號碼範圍內從新到舊指定數量版本的資料。

time_range

讀取版本號碼範圍或特定版本號碼的資料。更多資訊,請參見TimeRange

重要

max_versions與time_range必須至少設定一個。

  • 如果僅設定max_versions,則最多返回所有版本中從新到舊指定數量版本的資料。

  • 如果僅設定time_range,則返回該範圍內所有資料或指定版本資料。

  • 如果同時設定max_versions和time_range,則最多返回版本號碼範圍內從新到舊指定數量版本的資料。

  • 如果查詢一個範圍的資料,則需要設定start_time和end_time。start_time和end_time分別表示起始時間戳記和結束時間戳記,範圍為前閉後開區間,即[start_time, end_time)

  • 如果查詢特定版本號碼的資料,則需要設定specific_time。specific_time表示特定的時間戳記。

specific_time和[start_time, end_time)中只需要設定一個。

時間戳記的單位為毫秒,最小值為0,最大值為INT64.MAX

columns_to_get

讀取的列集合,列名可以是主鍵列或屬性列。

  • 如果不設定返回的列名,則返回整行資料。

  • 如果設定了返回的列名,當某行中指定的列均不存在時,則不返回該行,即傳回值為null;當某行中存在部分指定的列時,則返回該行且只返回存在的列。

說明
  • 查詢一行資料時,預設返回此行所有列的資料。如果需要只返回特定列,可以通過設定columns_to_get參數限制。如果將col0和col1加入到columns_to_get中,則只返回col0和col1列的值。

  • 如果某行資料的主鍵屬於讀取範圍,但是該行資料不包含指定返回的列,那麼返回結果中不包含該行資料。

  • 當columns_to_get和column_filter同時使用時,執行順序是先擷取columns_to_get指定的列,再在返回的列中進行條件過濾。

start_column

讀取的起始列,主要用於寬行讀,返回的結果中包含當前起始列。

列的順序按照列名的字典序排序。例如一張表有“a”、“b”、“c”三列,讀取時設定start_column為“b”,則會從“b”列開始讀,返回“b”、“c”兩列。

end_column

讀取時的結束列,主要用於寬行讀,返回的結果中不包含當前結束列。

列的順序按照列名的字典序排序。例如一張表有“a”、“b”、“c”三列,讀取時指定end_column為“b”,則讀到“b”列時會結束,返回“a”列。

token

寬行讀取時下一次讀取的位置,暫不可用。

column_filter

使用過濾器,在服務端對讀取結果再進行一次過濾,只返回符合過濾器中條件的資料行。更多資訊,請參見過濾器

說明

當columns_to_get和column_filter同時使用時,執行順序是先擷取columns_to_get指定的列,再在返回的列中進行條件過濾。

請求格式

$result = $client->getRange([
    'table_name' => '<string>',                                     //設定表名稱。
    'inclusive_start_primary_key' => [                              //設定起始主鍵。
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'exclusive_end_primary_key' => [                                //設定結束主鍵。
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'direction' => <Direction>,                                     //設定讀取方向。
    'limit' => <Direction>,
    'max_versions' => <integer>,
    'time_range' => [
        'start_time' => <integer>,
        'end_time' => <integer>,
        'specific_time' => <integer>
    ],
    'start_column' => '<string>',
    'end_column' => '<string>',
    'token' => '<string>',
    'columns_to_get' => [
        '<string>',
        '<string>',
        //...   
    ],
    'column_filter' =>  <ColumnCondition>
]);      

響應參數

參數

說明

consumed

本次操作消耗服務能力單元的值。

capacity_unit表示使用的讀寫能力單元。

  • read:讀輸送量

  • write:寫輸送量

primary_key

主鍵的值,和請求時一致。

attribute_columns

屬性列的值。

  • 每一項的順序是屬性名稱、屬性值ColumnValue、屬性類型ColumnType、時間戳記。

    時間戳記為64位整數,單位為毫秒,用於表示屬性列資料的多個不同的版本。

  • 返回結果中的屬性會按照屬性名稱的字典序升序,屬性的多個版本按時間戳記降序。

  • 其順序不保證與請求中的columns_to_get一致。

next_start_primary_key

根據返回結果中的next_start_primary_key判斷資料是否全部讀取。

  • 當返回結果中next_start_primary_key不為空白時,可以使用此傳回值作為下一次GetRange操作的起始點繼續讀取資料。

  • 當返回結果中next_start_primary_key為空白時,表示讀取範圍內的資料全部返回。

結果格式

[
    'consumed' => [
        'capacity_unit' => [
            'read' => <integer>,
            'write' => <integer>
        ]
    ],
    'next_start_primary_key' => [ 
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'rows' => [
        [
            'primary_key' => [ 
                ['<string>', <PrimaryKeyValue>], 
                ['<string>', <PrimaryKeyValue>],
                ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
            ],  
            'attribute_columns' => [
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>]
            ]
        ],
        //其他行。
    ]
]
            

樣本

以下樣本用於按照範圍讀取資料。

//尋找PK0從1到4(左閉右開)的資料。
//範圍的邊界需要提供完整的主鍵,如果查詢的範圍不涉及到某一列值的範圍,則需要將該列設定為無窮大(INF_MAX)或者無窮小(INF_MIN)。
$startPK = [
    ['PK0', 1], 
    ['PK1', null, PrimaryKeyTypeConst::CONST_INF_MIN]  //'INF_MIN'表示最小值。
];
//範圍的邊界需要提供完整的主鍵,如果查詢的範圍不涉及到某一列值的範圍,則需要將該列設定為無窮大(INF_MAX)或者無窮小(INF_MIN)。
$endPK = [
    ['PK0', 4], 
    ['PK1', null, PrimaryKeyTypeConst::CONST_INF_MAX]  //'INF_MAX'表示最大值。
];
$request = [
    'table_name' => 'SampleTable',
    'max_versions' => 1,                          //設定讀取最新版本。
    'direction' => DirectionConst::CONST_FORWARD, //設定正序查詢。
    'inclusive_start_primary_key' => $startPK,    //設定開始主鍵。
    'exclusive_end_primary_key' => $endPK,        //設定結束主鍵。
    'limit' => 10                                 //設定最多返回10行資料。
];
$response = $otsClient->getRange ($request);
print "Read CU Consumed: {$response['consumed']['capacity_unit']['read']}\n";

foreach ($response['rows'] as $rowData) {
  //處理每一行資料。
}           

詳細程式碼範例請參見下表。

樣本

說明

GetRange1.php

展示了GetRange的用法。

GetRange2.php

展示了GetRange指定擷取列的用法。

GetRange3.php

展示了GetRange指定擷取行數限制的用法。

GetRangeWithColumnFilter.php

展示了GetRange同時使用過濾器的用法。