寫入資料 - Tablestore

前提條件

已初始化Client，詳情請參見初始化。
已建立資料表並寫入資料。

插入單行資料

調用PutRow介面新寫入一行資料。如果該行已存在，則先刪除原行資料（原行的所有列以及所有版本的資料），再寫入新行資料。

介面

  /**
   * 插入資料到指定的行，如果該行不存在，則新增一行；如果該行存在，則覆蓋原有行。
   */
  putRow(params, callback)

參數


參數	說明
tableName	資料表名稱。
primaryKey	行的主鍵。说明設定的主鍵個數和類型必須和資料表的主鍵個數和類型一致。當主鍵為自增列時，只需將自增列的值設定為預留位置。更多資訊，請參見主鍵列自增。
condition	使用條件更新，可以設定原行的存在性條件或者原行中某列的列值條件。更多資訊，請參見條件更新。说明 RowExistenceExpectation.IGNORE表示無論此行是否存在均會插入新資料，如果之前行已存在，則寫入資料時會覆蓋原有資料。 RowExistenceExpectation.EXPECT_EXIST表示只有此行存在時才會插入新資料，寫入資料時會覆蓋原有資料。 RowExistenceExpectation.EXPECT_NOT_EXIST表示只有此行不存在時才會插入資料。
attributeColumns	行的屬性列。每一項的順序是屬性名稱、屬性類型（可選）、屬性值、時間戳記（可選）。時間戳記即資料的版本號碼。更多資訊，請參見資料版本和生命週期。資料的版本號碼可以由系統自動產生或者自訂，如果不設定此參數，則預設由系統自動產生。當由系統自動產生資料的版本號碼時，系統預設將目前時間的毫秒單位時間戳記（從1970-01-01 00:00:00 UTC計算起的毫秒數）作為資料的版本號碼。當自訂資料的版本號碼時，版本號碼需要為64位的毫秒單位時間戳記且在有效版本範圍內。
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': 'Table Store' },
    { '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	更新的屬性列。增加或更新資料時，需要設定屬性名稱、屬性值、屬性類型（可選）、時間戳記（可選）。時間戳記即資料的版本號碼，可以由系統自動產生或者自訂，如果不設定此參數，則預設由系統自動產生。更多資訊，請參見資料版本和生命週期。當由系統自動產生資料的版本號碼時，系統預設將目前時間的毫秒單位時間戳記（從1970-01-01 00:00:00 UTC計算起的毫秒數）作為資料的版本號碼。當自訂資料的版本號碼時，版本號碼需要為64位的毫秒單位時間戳記且在有效版本範圍內。刪除屬性列特定版本的資料時，只需要設定屬性名稱和時間戳記。時間戳記是64位整數，單位為毫秒，表示某個特定版本的資料。刪除屬性列時，只需要設定屬性名稱。说明刪除一行的全部屬性列不等同於刪除該行，如果需要刪除該行，請使用DeleteRow操作。

樣本

更新一行資料。

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

注意事項

由於批量寫入可能存在部分行失敗的情況，失敗行的Index及錯誤資訊在返回的BatchWriteRowResponse中，但並不拋出異常。因此調用BatchWriteRow介面時，需要檢查傳回值，判斷每行的狀態是否成功；如果不檢查傳回值，則可能會忽略掉部分操作的失敗。

當服務端檢查到某些操作出現參數錯誤時，BatchWriteRow介面可能會拋出參數錯誤的異常，此時該請求中所有的操作都未執行。

介面

/**
 * 批量修改行。
 */
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。