Tablestore提供了GetRow介面用於讀取單行資料以及BatchGetRow、GetRange等介面用於讀取多行資料。
前提條件
- 已初始化Client,詳情請參見初始化。
- 已建立資料表並寫入資料。
讀取單行資料
調用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必須至少設定一個。
|
time_range | 讀取版本號碼範圍或特定版本號碼的資料。更多資訊,請參見TimeRange。 说明 max_versions與time_range必須至少設定一個。
specific_time和 時間戳記的單位為毫秒,最小值為0,最大值為INT64.MAX。 |
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表示使用的讀寫能力單元。
|
primary_key | 主鍵的值,和請求時一致。 说明 如果該行不存在,則primary_key為空白列表[]。 |
attribute_columns | 屬性列的值。 说明 如果該行不存在,則attribute_columns為空白列表[]。
|
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>'
]
樣本
- 樣本1
讀取一行,設定讀取最新版本的資料和讀取的列。
$request = [ 'table_name' => 'MyTable', 'primary_key' => [ //設定主鍵。 ['PK0', 123], ['PK1', 'abc'] ], 'max_versions' => 1, //設定讀取最新版本。 'columns_to_get' => ['Col0'] //設定讀取的列。 ]; $response = $otsClient->getRow ($request);
- 樣本2
在讀取一行資料時使用過濾器。
$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介面時相同,也支援使用過濾器。
批量讀取的所有行採用相同的參數條件,例如ColumnsToGet=[colA]
,則要讀取的所有行都唯讀取colA列。
BatchGetRow的各個子操作獨立執行,Tablestore會分別返回各個子操作的執行結果。
注意事項
由於批量讀取可能存在部分行失敗的情況,失敗行的錯誤資訊在返回的BatchGetRowResponse中,但並不拋出異常。因此調用BatchGetRow介面時,需要檢查傳回值,判斷每行的狀態是否成功。
介面
/**
* 讀取指定的多行資料。
* 請注意BatchGetRow在部分行讀取失敗時,會在返回的$response中表示,而不是拋出異常。更多資訊,請參見處理BatchGetRow的返回範例。
* @api
* @param [] $request 請求參數。
* @return [] 請求返回。
* @throws OTSClientException 當參數檢查出錯或服務端返回校正出錯時。
* @throws OTSServerException 當OTS服務端返回錯誤時。
*/
public function batchGetRow(array $request);
請求參數
- 增加了資料表的層級結構,可以一次讀取多個資料表的資料。
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>
],
//其他資料表。
]
]);
響應參數
參數 | 說明 |
---|---|
table_name | 資料表名稱。 |
is_ok | 該行操作是否成功。
|
error | 用於在操作失敗時的響應訊息中表示錯誤資訊。
|
consumed | 本次操作消耗服務能力單元的值。 capacity_unit表示使用的讀寫能力單元。
|
primary_key | 主鍵的值,和請求時一致。 说明 如果該行不存在,則primary_key為空白列表[]。 |
attribute_columns | 屬性列的值。 说明 如果該行不存在,則attribute_columns為空白列表[]。
|
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操作支援按照確定範圍進行正序讀取和逆序讀取,可以設定要讀取的行數。如果範圍較大,已掃描的行數或者資料量超過一定限制,會停止掃描,並返回已擷取的行和下一個主鍵資訊。您可以根據返回的下一個主鍵資訊,繼續發起請求,擷取範圍內剩餘的行。
注意事項
GetRange操作遵循最左匹配原則,讀取資料時,依次比較第一主鍵列到第四主鍵列。例如資料表的主鍵包括PK1、PK2、PK3三個主鍵列,讀取資料時,優先比較PK1是否在開始主鍵與結束主鍵的範圍內,如果PK1在設定的主鍵範圍內,則不會再比較其他的主鍵,返回在PK1主鍵範圍內的資料;如果PK1不在設定的主鍵範圍內,則繼續比較PK2是否在開始主鍵與結束主鍵的範圍內,以此類推。
- 掃描的行資料大小之和達到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);
參數
- 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表示無限大,任何類型的值都比它小。
資料表中的行按主鍵從小到大排序,讀取範圍是一個左閉右開的區間,正序讀取時,返回的是大於等於起始主鍵且小於結束主鍵的所有的行。 |
exclusive_end_primary_key | |
direction | 讀取方向。
例如同一表中有兩個主鍵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必須至少設定一個。
|
time_range | 讀取版本號碼範圍或特定版本號碼的資料。更多資訊,請參見TimeRange。 说明 max_versions與time_range必須至少設定一個。
specific_time和 時間戳記的單位為毫秒,最小值為0,最大值為INT64.MAX。 |
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表示使用的讀寫能力單元。
|
primary_key | 主鍵的值,和請求時一致。 |
attribute_columns | 屬性列的值。
|
next_start_primary_key | 根據返回結果中的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同時使用過濾器的用法。 |