表格存储提供了PutRow和UpdateRow接口用于写入单行数据以及BatchWriteRow接口用于批量写入数据。

如果需要了解表格存储各场景的应用案例,请参见快速玩转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': '表格存储' },
    { '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的各个子操作独立执行,表格存储会分别返回各个子操作的执行结果。

注意事项

由于批量写入可能存在部分行失败的情况,失败行的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