如果需要了解表格存儲各場景的應用案例，請參見快速玩轉Tablestore入門與實戰。

查詢方式

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

前提條件

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

讀取單行數據

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

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

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

接口

/*
 * 根據給定的主鍵讀取單行數據。
 */
getRow(params, callback)

參數

示例

讀取一行數據。

var TableStore = require('../index.js');
var Long = TableStore.Long;
var client = require('./client');

var params = {
  tableName: "sampleTable",
  primaryKey: [{ 'gid': Long.fromNumber(20004) }, { 'uid': Long.fromNumber(20004) }],
  maxVersions: 2 //最多可讀取的版本數，設置為2即代表最多可讀取2個版本。
};
var condition = new TableStore.CompositeCondition(TableStore.LogicalOperator.AND);
condition.addSubCondition(new TableStore.SingleColumnCondition('name', 'john', TableStore.ComparatorType.EQUAL));
condition.addSubCondition(new TableStore.SingleColumnCondition('addr', 'china', TableStore.ComparatorType.EQUAL));

params.columnFilter = condition;

client.getRow(params, function (err, data) {
  if (err) {
    console.log('error:', err);
    return;
  }
  console.log('success:', data);
});                  

詳細代碼請參見GetRow@GitHub。

批量讀取數據

調用BatchGetRow接口一次請求讀取多行數據，也支持一次對多張表進行讀取。BatchGetRow由多個GetRow子操作組成。構造子操作的過程與使用GetRow接口時相同。

BatchGetRow的各個子操作獨立執行，表格存儲會分別返回各個子操作的執行結果。

注意事項

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

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

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

接口

/**
 * 批量讀取一個或多個表中的若干行數據。
 */
batchGetRow(params, callback)  

參數

示例

批量一次讀取多個數據表中的數據，并在出錯時進行重試。

var client = require('./client');
var TableStore = require('../index.js');
var Long = TableStore.Long;

var params = {
    tables: [{
        tableName: 'sampleTable',
        primaryKey: [
            [{ 'gid': Long.fromNumber(20013) }, { 'uid': Long.fromNumber(20013) }],
            [{ 'gid': Long.fromNumber(20015) }, { 'uid': Long.fromNumber(20015) }]
        ],
        startColumn: "col2",
        endColumn: "col4"
    },
    {
        tableName: 'notExistTable',
        primaryKey: [
            [{ 'gid': Long.fromNumber(10001) }, { 'uid': Long.fromNumber(10001) }]
        ]
    }
    ],
};

var maxRetryTimes = 3;
var retryCount = 0;

function batchGetRow(params) {
    client.batchGetRow(params, function (err, data) {
        if (err) {
            console.log('error:', err);
            return;
        }

        var isAllSuccess = true;
        var retryRequest = { tables: [] };
        for (var i = 0; i < data.tables.length; i++) {
            var failedRequest = { tableName: data.tables[i][0].tableName, primaryKey: [] };

            for (var j = 0; j < data.tables[i].length; j++) {
                if (!data.tables[i][j].isOk && null != data.tables[i][j].primaryKey) {
                    isAllSuccess = false;
                    var pks = [];
                    for (var k in data.tables[i][j].primaryKey) {
                        var name = data.tables[i][j].primaryKey[k].name;
                        var value = data.tables[i][j].primaryKey[k].value;
                        var kp = {};
                        kp[name] = value;
                        pks.push(kp);
                    }
                    failedRequest.primaryKey.push(pks);

                } else {
                    // get success data
                }
            }

            if (failedRequest.primaryKey.length > 0) {
                retryRequest.tables.push(failedRequest);
            }
        }

        if (!isAllSuccess && retryCount++ < maxRetryTimes) {
            batchGetRow(retryRequest);
        }

        console.log('success:', data);
    });
}

batchGetRow(params, maxRetryTimes);                    

詳細代碼請參見BatchGetRow@GitHub。

范圍讀取數據

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

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

注意事項

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

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

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

• 掃描的行數等于5000。

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

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

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

接口

/**
 * 讀取指定主鍵范圍內的數據。
 */
getRange(params, callback)                   

參數

示例

按照范圍讀取數據。

var Long = TableStore.Long;
var client = require('./client');

var params = {
  tableName: "sampleTable",
  direction: TableStore.Direction.FORWARD,
  inclusiveStartPrimaryKey: [{ "gid": TableStore.INF_MIN }, { "uid": TableStore.INF_MIN }],
  exclusiveEndPrimaryKey: [{ "gid": TableStore.INF_MAX }, { "uid": TableStore.INF_MAX }],
  limit: 50
};

client.getRange(params, function (err, data) {
  if (err) {
    console.log('error:', err);
    return;
  }

  //如果data.next_start_primary_key不為空，則繼續讀取。
  if (data.next_start_primary_key) {

  }

  console.log('success:', data);
});                  

詳細代碼請參見GetRange@GitHub。