表格存儲提供了單行插入、單行更新和批量寫入的寫入方式用于寫入數據到數據表。當要寫入數據到數據表時,您需要指定完整主鍵以及要增刪改的屬性列。在高并發應用中寫入數據時,您可以配置行存在性條件或者列條件實現按照指定條件更新數據。
如果需要了解表格存儲各場景的應用案例,請參見快速玩轉Tablestore入門與實戰。
前提條件
已初始化Client,詳情請參見初始化Client。
已創建數據表并寫入數據。
插入單行數據
調用PutRow接口新寫入一行數據。如果該行已存在,則先刪除原行數據(原行的所有列以及所有版本的數據),再寫入新行數據。
接口
/**
* 插入數據到指定的行,如果該行不存在,則新增一行;如果該行存在,則覆蓋原有行。
*/
putRow(params, callback)
參數
參數 | 說明 |
tableName | 數據表名稱。 |
primaryKey | 行的主鍵。主鍵包括主鍵列名、主鍵類型和主鍵值。 重要
|
condition | 使用條件更新,可以設置原行的存在性條件或者原行中某列的列值條件。更多信息,請參見條件更新。 說明
|
attributeColumns | 行的屬性列。每一項的順序是屬性名、屬性類型(可選)、屬性值、時間戳(可選)。
|
returnContent | 表示返回類型。 returnType:設置為TableStore.ReturnType.Primarykey,表示返回主鍵值,主要用于主鍵列自增場景。 |
示例
以下示例用于插入一行數據。
var TableStore = require('../index.js');
var Long = TableStore.Long;
var client = require('./client');
var currentTimeStamp = Date.now();
var params = {
tableName: "sampleTable",
condition: new TableStore.Condition(TableStore.RowExistenceExpectation.IGNORE, null),
primaryKey: [{ 'gid': Long.fromNumber(20013) }, { 'uid': Long.fromNumber(20013) }],
attributeColumns: [
{ 'col1': '表格存儲' },
{ 'col2': '2', 'timestamp': currentTimeStamp },
{ 'col3': 3.1 },
{ 'col4': -0.32 },
{ 'col5': Long.fromNumber(123456789) }
],
returnContent: { returnType: TableStore.ReturnType.Primarykey }
};
client.putRow(params, function (err, data) {
if (err) {
console.log('error:', err);
return;
}
console.log('success:', data);
});
詳細代碼請參見PutRow@GitHub。
更新單行數據
調用UpdateRow接口更新一行數據,可以增加和刪除一行中的屬性列,刪除屬性列指定版本的數據,或者更新已存在的屬性列的值。如果更新的行不存在,則新增一行數據。
當UpdateRow請求中只包含刪除指定的列且該行不存在時,則該請求不會新增一行數據。
接口
/**
* 更新指定行的數據。如果該行不存在,則新增一行;如果該行存在,則根據請求的內容在此行中新增、修改或者刪除指定列的值。
*/
updateRow(params, callback)
參數
參數 | 說明 |
tableName | 數據表名稱。 |
primaryKey | 行的主鍵。 重要 設置的主鍵個數和類型必須和數據表的主鍵個數和類型一致。 |
condition | 使用條件更新,可以設置原行的存在性條件或者原行中某列的列值條件。更多信息,請參見條件更新。 |
updateOfAttributeColumns | 更新的屬性列。
|
示例
以下示例用于更新一行數據。
var TableStore = require('../index.js');
var Long = TableStore.Long;
var client = require('./client');
var params = {
tableName: "sampleTable",
condition: new TableStore.Condition(TableStore.RowExistenceExpectation.IGNORE, null),
primaryKey: [{ 'gid': Long.fromNumber(9) }, { 'uid': Long.fromNumber(90) }],
updateOfAttributeColumns: [
{ 'PUT': [{ 'col4': Long.fromNumber(4) }, { 'col5': '5' }, { 'col6': Long.fromNumber(6) }] },
{ 'DELETE': [{ 'col1': Long.fromNumber(1496826473186) }] },
{ 'DELETE_ALL': ['col2'] }
]
};
client.updateRow(params,
function (err, data) {
if (err) {
console.log('error:', err);
return;
}
console.log('success:', data);
});
詳細代碼請參見UpdateRow@GitHub。
批量寫入數據
調用BatchWriteRow接口在一次請求中進行批量寫入操作或者一次對多張表進行寫入。
BatchWriteRow操作由多個PutRow、UpdateRow、DeleteRow子操作組成,構造子操作的過程與使用PutRow接口、UpdateRow接口和DeleteRow接口時相同。
BatchWriteRow的各個子操作獨立執行,表格存儲會分別返回各個子操作的執行結果。
注意事項
由于批量寫入可能存在部分行失敗的情況,失敗行的Index及錯誤信息在返回的BatchWriteRowResponse中,但并不拋出異常。因此調用BatchWriteRow接口時,需要檢查返回值,判斷每行的狀態是否成功;如果不檢查返回值,則可能會忽略掉部分操作的失敗。
當服務端檢查到某些操作出現參數錯誤時,BatchWriteRow接口可能會拋出參數錯誤的異常,此時該請求中所有的操作都未執行。
BatchWriteRow操作單次支持寫入的最大行數為200行,且所有行的數據量總和不能超過4 MB。
接口
/**
* 對多個數據表中的多行數據進行增加、刪除或者更新操作。
*/
batchWriteRow(params, callback)
參數
本操作是PutRow、UpdateRow、DeleteRow的組合。
增加了數據表的層級結構,可以一次處理多個數據表。
tables以數據表為單位組織,后續為各個數據表的操作,設置需要寫入、修改或刪除的行信息。
增加了type參數,用于區分操作類型。
操作類型可以為PUT、UPDATE、DELETE。
當操作類型為PUT或UPDATE時,primaryKey和attributeColumns有效。
當操作類型為DELETE時,primaryKey有效。
示例
以下示例用于批量寫入數據。
var client = require('./client');
var TableStore = require('../index.js');
var Long = TableStore.Long;
var params = {
tables: [
{
tableName: 'sampleTable',
rows: [
{
type: 'UPDATE',
condition: new TableStore.Condition(TableStore.RowExistenceExpectation.IGNORE, null),
primaryKey: [{ 'gid': Long.fromNumber(20010) }, { 'uid': Long.fromNumber(20010) }],
attributeColumns: [{ 'PUT': [{ 'col1': 'test3' }, { 'col2': 'test4' }] }],
returnContent: { returnType: 1 }
},
{
type: 'PUT',
condition: new TableStore.Condition(TableStore.RowExistenceExpectation.IGNORE, null),
primaryKey: [{ 'gid': Long.fromNumber(20020) }, { 'uid': Long.fromNumber(20020) }],
attributeColumns: [{ 'col1': 'test1' }, { 'col2': 'test2' }],
returnContent: { returnType: TableStore.ReturnType.Primarykey }
},
{
type: 'DELETE',
condition: new TableStore.Condition(TableStore.RowExistenceExpectation.IGNORE, null),
primaryKey: [{ 'gid': Long.fromNumber(20018) }, { 'uid': Long.fromNumber(20018) }],
}
]
}
],
};
client.batchWriteRow(params, function (err, data) {
if (err) {
console.log('error:', err);
return;
}
console.log('success:', data);
});
詳細代碼請參見BatchWriteRow@GitHub。