全部產品
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,詳情請參見初始化Client

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

讀取單行資料

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

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

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

介面

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

參數

參數

說明

tableName

資料表名稱。

primaryKey

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

重要

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

columnsToGet

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

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

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

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

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

maxVersions

最多讀取的版本數。

重要

maxVersions與timeRange必須至少設定一個。

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

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

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

timeRange

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

重要

maxVersions與timeRange必須至少設定一個。

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

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

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

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

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

specificTime和[startTime, endTime)中只需要設定一個。

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

columnFilter

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

說明

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

樣本

讀取一行資料。

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的各個子操作獨立執行,Tablestore會分別返回各個子操作的執行結果。

注意事項

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

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

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

介面

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

參數

BatchGetRow和GetRow的區別如下:

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

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

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

    說明

    設定主鍵時,需要指定行資料的完整主鍵(包括主鍵名、主鍵類型和主索引值),並確保對應主鍵在表中存在。如果表中不存在該主鍵,則返回結果中該主鍵對應行資料為空白。

樣本

批量一次讀取多個資料表中的資料,並在出錯時進行重試。

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

說明

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

注意事項

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

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

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

  • 掃描的行數等於5000。

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

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

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

介面

/**
 * 讀取指定主鍵範圍內的資料。
 */
getRange(params, callback)                   

參數

參數

說明

tableName

資料表名稱。

direction

讀取方向。

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

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

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

inclusiveStartPrimaryKey

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

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

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

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

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

exclusiveEndPrimaryKey

limit

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

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

columnsToGet

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

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

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

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

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

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

maxVersions

最多讀取的版本數。

重要

maxVersions與timeRange必須至少設定一個。

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

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

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

timeRange

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

重要

maxVersions與timeRange必須至少設定一個。

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

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

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

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

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

specificTime和[startTime, endTime)中只需要設定一個。

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

columnFilter

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

說明

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

nextStartPrimaryKey

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

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

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

樣本

按照範圍讀取資料。

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