表格存储提供了PutRow、GetRow、UpdateRow和DeleteRow等单行操作的接口。

如需了解表格存储各场景的应用案例，请参见适用场景。

前提条件

  • 已初始化Client，详情请参见初始化。
  • 已创建数据表并写入数据。

插入一行数据（PutRow）

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。

读取一行数据（GetRow）

GetRow接口用于读取一行数据。

读取的结果可能有如下两种：
  • 如果该行存在，则返回该行的各主键列以及属性列。
  • 如果该行不存在，则返回中不包含行，并且不会报错。
  • 接口 
      /**
   * 根据给定的主键读取单行数据。
   */
  getRow(params, callback)
  • 参数
    参数 说明
    tableName 数据表名称。
    primaryKey 行的主键。
    说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
    columnsToGet 读取的列集合，列名可以是主键列或属性列。

    如果不设置返回的列名，则返回整行数据。

    说明
    • 查询一行数据时，默认返回此行所有列的数据。如果需要只返回特定列，可以通过设置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。

更新一行数据（UpdateRow）

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。

删除一行数据（DeleteRow）

DeleteRow接口用于删除一行数据。如果删除的行不存在，则不会发生任何变化。

  • 接口 
      /**
   * 删除一行数据。
   */
  deleteRow(params, callback)
  • 参数
    参数 说明
    tableName 数据表名称。
    primaryKey 行的主键。
    说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
    condition 使用条件更新，可以设置原行的存在性条件或者原行中某列的列值条件，详情请参见条件更新。
  • 示例

    删除一行数据。

    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(8) }, { 'uid': Long.fromNumber(80) }]
};

client.deleteRow(params, function (err, data) {
    if (err) {
        console.log('error:', err);
        return;
    }

    console.log('success:', data);
});

    详细代码请参见DeleteRow@GitHub。