Tablestore提供了GetRow介面用於讀取單行資料以及BatchGetRow、GetRange等介面用於讀取多行資料。
前提條件
- 已初始化Client,詳情請參見初始化。
- 已建立資料表並寫入資料。
讀取單行資料
調用GetRow介面讀取一行資料。
- 如果該行存在,則返回該行的各主鍵列以及屬性列。
- 如果該行不存在,則返回中不包含行,並且不會報錯。
介面
/*
* 根據給定的主鍵讀取單行資料。
*/
getRow(params, callback)
參數
參數 | 說明 |
---|---|
tableName | 資料表名稱。 |
primaryKey | 行的主鍵。 说明 設定的主鍵個數和類型必須和資料表的主鍵個數和類型一致。 |
columnsToGet | 讀取的列集合,列名可以是主鍵列或屬性列。 如果不設定返回的列名,則返回整行資料。 说明
|
maxVersions | 最多讀取的版本數。 说明 maxVersions與timeRange必須至少設定一個。
|
timeRange | 讀取版本號碼範圍或特定版本號碼的資料。更多資訊,請參見TimeRange。 说明 maxVersions與timeRange必須至少設定一個。
specificTime和 時間戳記的單位為毫秒,最小值為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介面時相同,也支援使用過濾器。
批量讀取的所有行採用相同的參數條件,例如ColumnsToGet=[colA]
,則要讀取的所有行都唯讀取colA列。
BatchGetRow的各個子操作獨立執行,Tablestore會分別返回各個子操作的執行結果。
注意事項
由於批量讀取可能存在部分行失敗的情況,失敗行的錯誤資訊在返回的BatchGetRowResponse中,但並不拋出異常。因此調用BatchGetRow介面時,需要檢查傳回值,判斷每行的狀態是否成功。
介面
/**
* 批量讀取一個或多個表中的若干行資料。
*/
batchGetRow(params, callback)
參數
- 增加了資料表的層級結構,可以一次讀取多個資料表的資料。
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操作支援按照確定範圍進行正序讀取和逆序讀取,可以設定要讀取的行數。如果範圍較大,已掃描的行數或者資料量超過一定限制,會停止掃描,並返回已擷取的行和下一個主鍵資訊。您可以根據返回的下一個主鍵資訊,繼續發起請求,擷取範圍內剩餘的行。
注意事項
GetRange操作遵循最左匹配原則,讀取資料時,依次比較第一主鍵列到第四主鍵列。例如資料表的主鍵包括PK1、PK2、PK3三個主鍵列,讀取資料時,優先比較PK1是否在開始主鍵與結束主鍵的範圍內,如果PK1在設定的主鍵範圍內,則不會再比較其他的主鍵,返回在PK1主鍵範圍內的資料;如果PK1不在設定的主鍵範圍內,則繼續比較PK2是否在開始主鍵與結束主鍵的範圍內,以此類推。
- 掃描的行資料大小之和達到4 MB。
- 掃描的行數等於5000。
- 返回的行數等於最大返回行數。
- 當前剩餘的預留讀輸送量已全部使用,餘量不足以讀取下一條資料。
當使用GetRange掃描的資料量較大時,Tablestore每次請求僅會掃描一次(行數大於5000或者大小大於4 MB停止掃描),超過限制的資料不會繼續返回,需要通過翻頁繼續擷取後面的資料。
介面
/**
* 讀取指定主鍵範圍內的資料。
*/
getRange(params, callback)
參數
參數 | 說明 |
---|---|
tableName | 資料表名稱。 |
direction | 讀取方向。
例如同一表中有兩個主鍵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表示無限大,任何類型的值都比它小。
資料表中的行按主鍵從小到大排序,讀取範圍是一個左閉右開的區間,正序讀取時,返回的是大於等於起始主鍵且小於結束主鍵的所有的行。 |
exclusiveEndPrimaryKey | |
limit | 資料的最大返回行數,此值必須大於 0。 Table Store按照正序或者逆序返回指定的最大返回行數後即結束該操作的執行,即使該區間內仍有未返回的資料。此時可以通過返回結果中的nextStartPrimaryKey記錄本次讀取到的位置,用於下一次讀取。 |
columnsToGet | 讀取的列集合,列名可以是主鍵列或屬性列。 如果不設定返回的列名,則返回整行資料。 说明
|
maxVersions | 最多讀取的版本數。 说明 maxVersions與timeRange必須至少設定一個。
|
timeRange | 讀取版本號碼範圍或特定版本號碼的資料。更多資訊,請參見TimeRange。 说明 maxVersions與timeRange必須至少設定一個。
specificTime和 時間戳記的單位為毫秒,最小值為0,最大值為Long.MAX_VALUE。 |
columnFilter | 使用過濾器,在服務端對讀取結果再進行一次過濾,只返回符合過濾器中條件的資料行。更多資訊,請參見過濾器。 说明 當columnsToGet和columnFilter同時使用時,執行順序是先擷取columnsToGet指定的列,再在返回的列中進行條件過濾。 |
nextStartPrimaryKey | 根據返回結果中的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。