表格存储提供了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