查詢方式

表格存儲提供的數據讀取接口包括GetRow、BatchGetRow和GetRange。讀取數據時，請根據實際查詢場景使用相應查詢方式讀取數據。

前提條件

• 已初始化Client，詳情請參見初始化。
• 已創(chuàng)建數據表并寫入數據。

讀取單行數據

調用GetRow接口讀取一行數據。讀取的結果可能有如下兩種：

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

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

接口

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

請求參數

請求格式

$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' => <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的各個子操作獨立執(zhí)行，表格存儲會分別返回各個子操作的執(zhí)行結果。

注意事項

• 由于批量讀取可能存在部分行失敗的情況，失敗行的錯誤信息在返回的BatchGetRowResponse中，但并不拋出異常。因此調用BatchGetRow接口時，需要檢查返回值，判斷每行的狀態(tài)是否成功。

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

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

接口

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

請求參數

請求格式

$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_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";
    }
  }
}            

詳細代碼示例請參見下表。

范圍讀取數據

調用GetRange接口讀取一個范圍內的數據。

GetRange操作支持按照確定范圍進行正序讀取和逆序讀取，可以設置要讀取的行數。如果范圍較大，已掃描的行數或者數據量超過一定限制，會停止掃描，并返回已獲取的行和下一個主鍵信息。您可以根據返回的下一個主鍵信息，繼續(xù)發(fā)起請求，獲取范圍內剩余的行。

注意事項

GetRange操作遵循最左匹配原則，讀取數據時，依次比較第一主鍵列到第四主鍵列。例如表的主鍵包括PK1、PK2、PK3三個主鍵列，讀取數據時，優(yōu)先比較PK1是否在開始主鍵與結束主鍵的范圍內，如果PK1在設置的主鍵范圍內，則不會再比較其他的主鍵，返回在PK1主鍵范圍內的數據；如果PK1在設置的主鍵邊界上，則繼續(xù)比較PK2是否在開始主鍵與結束主鍵的范圍內，以此類推。關于范圍查詢原理的更多信息，請參見GetRange范圍查詢詳解。

GetRange操作可能在如下情況停止執(zhí)行并返回數據。

• 掃描的行數據大小之和達到4 MB。

• 掃描的行數等于5000。

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

• 當前剩余的預留讀吞吐量已全部使用，余量不足以讀取下一條數據。

當使用GetRange掃描的數據量較大時，表格存儲每次請求僅會掃描一次（行數大于5000或者大小大于4 MB停止掃描），超過限制的數據不會繼續(xù)返回，需要通過翻頁繼續(xù)獲取后面的數據。

接口

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

參數

請求格式

$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' => <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）或者無窮?。↖NF_MIN）。
$startPK = [
    ['PK0', 1], 
    ['PK1', null, PrimaryKeyTypeConst::CONST_INF_MIN]  //'INF_MIN'表示最小值。
];
//范圍的邊界需要提供完整的主鍵，如果查詢的范圍不涉及到某一列值的范圍，則需要將該列設置為無窮大（INF_MAX）或者無窮?。↖NF_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) {
  //處理每一行數據。
}           

詳細代碼示例請參見下表。