Tablestore provides the following single-row operations: PutRow, GetRow, UpdateRow, and DeleteRow.

Prerequisites

  • The OTSClient instance is initialized. For more information, see Initialization.
  • A data table is created. Data is written to the table.

PutRow

You can call this operation to insert a row. If the row exists, data of all versions in all columns of the row is deleted before new data is inserted.

  • Operations
      /**
       * Insert data into a specified row. If the row exists, the existing data is overwritten. Otherwise, a new row is added.
       */
      putRow(params, callback) 
                        
  • Parameters
    Parameter Description
    tableName The name of the table.
    primaryKey The primary key of the row.
    Note
    • The configured number and types of primary key columns must be consistent with the actual number and types of primary key columns of the table.
    • For an auto-increment primary key column, you need only to set the value of the auto-increment primary key column to a placeholder. For more information, see Configure an auto-increment primary key column.
    condition You can use conditional update to set a row existence condition or columns-based conditions for the row. For more information, see Configure conditional update.
    Note
    • RowExistenceExpectation.IGNORE indicates that new data is inserted into a row regardless of whether the specified row exists or not. If the specified row exists, the existing data is overwritten.
    • RowExistenceExpectation.EXPECT_EXIST indicates that new data is inserted only when the specified row exists. The existing data is overwritten.
    • RowExistenceExpectation.EXPECT_NOT_EXIST indicates that data is inserted only when the specified row does not exist.
    attributeColumns The attribute columns of the row.
    • Each attribute column is specified by parameters in the following sequence: the attribute column name, attribute column value type (optional), attribute column value, and timestamp (optional).
    • A timestamp is the data version number. For more information, see Max versions and TTL.

      You can customize a data version number or use the data version number generated by Tablestore. If you do not specify this parameter, the data version number generated by the system is used.

      • The version number generated by Tablestore is calculated based on the number of milliseconds that have elapsed since 00:00:00 UTC on January 1, 1970.
      • When you choose to specify the version number, ensure that the version number is a 64-bit timestamp accurate to the millisecond within the valid version range.
    returnContent The return type.

    returnType: Set the value to TableStore.ReturnType.Primarykey, which returns the primary key values. This parameter is used for auto-increment primary key columns.

  • Examples

    The following code provides an example on how to insert a row of data:

    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': 'Tablestore' },
        { '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);
    });
                        

    For the detailed sample code, visit PutRow@GitHub.

GetRow

You can call this operation to read a row of data.

The following results for the read request may be returned:
  • If the row exists, the primary key columns and attribute columns of the row are returned.
  • If the row does not exist, no row is returned and no error is reported.
  • Operations
      /**
       * Read a single row of data based on a specified primary key.
       */
      getRow(params, callback)
                        
  • Parameters
    Parameter Description
    tableName The name of the table.
    primaryKey The primary key of the row.
    Note The configured number and types of primary key columns must be consistent with the actual number and types of primary key columns of the table.
    columnsToGet The names of the columns to read. You can specify the names of primary key columns and the names of attribute columns.

    If you do not specify this parameter, all data in the row is returned.

    Note
    • By default, Tablestore returns the data from all columns of the row when you query a row. You can use the columnsToGet parameter to read data from specified columns. For example, Tablestore returns only the values of col0 and col1 if col0 and col1 are included in columnsToGet.
    • If columnsToGet and columnFilter are used at the same time, the system first obtains the columns specified by columnsToGet and then filters the returned columns.
    maxVersions The maximum number of versions that can be read.
    Note You must set at least one of the following parameters: maxVersions and timeRange.
    • If you specify only maxVersions, data of up to the specified number of versions is returned from the latest to the earliest.
    • If you specify only timeRange, all data whose versions are within the specified time range or data of the specified version is returned.
    • If you specify both maxVersions and timeRange, data of up to the specified number of versions within the time range is returned from the latest to the earliest.
    timeRange Specifies a range of versions to read or a version of data to read. For more information, see TimeRange.
    Note You must set at least one of the following parameters: maxVersions and timeRange.
    • If you specify only maxVersions, data of up to the specified number of versions is returned from the latest to the earliest.
    • If you specify only timeRange, all data whose versions are within the specified time range or data of the specified version is returned.
    • If you specify both maxVersions and timeRange, data of up to the specified number of versions within the time range is returned from the latest to the earliest.
    • To query data within a range, you must set startTime and endTime. startTime specifies the start timestamp. endTime specifies the end timestamp. The time range is a left-closed and right-open interval, which is [startTime, endTime).
    • To query data within a range of versions, set specificTime. specificTime specifies a specific timestamp.

    Only one of specificTime and [startTime, endTime) is required.

    Valid values: [0, Long.MAX_VALUE). Unit: milliseconds.

    columnFilter You can set filter conditions to filter the queried results on the server side. Only rows that meet the specified filter conditions are returned. For more information, see Configure a filter.
    Note If columnsToGet and columnFilter are used at the same time, the system first obtains the columns specified by columnsToGet and then filters the returned columns.
  • Examples

    The following code provides an example on how to read a row of data:

    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 // Specify the maximum number of versions that can be read. A value of 2 indicates that you can read a maximum of two versions of data.
    };
    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);
    });
                        

    For the detailed sample code, visit GetRow@GitHub.

UpdateRow

You can call this operation to update data of a specified row. You can add attribute columns to or delete attribute columns from a row, delete a specified version of data from an attribute column, or update the existing data in an attribute column. If the specified row does not exist, a new row is added.
Note If the UpdateRow request contains only columns to delete, and the specified row does not exist, a new row is not added.
  • Operations
      /**
       * Update the data of the specified row. If the row does not exist, a new row is added. If the row exists, the values of the specified columns are added, modified, or deleted based on the request content.
       */
      updateRow(params, callback)
                        
  • Parameters
    Parameter Description
    tableName The name of the table.
    primaryKey The primary key of the row.
    Note The configured number and types of primary key columns must be consistent with the actual number and types of primary key columns of the table.
    condition You can use conditional update to set a row existence condition or columns-based conditions for the row. For more information, see Configure conditional update.
    updateOfAttributeColumns The attribute columns you want to update.
    • To add an attribute column or update the value of an existing attribute column, you must specify the name, value and type (optional) of the attribute column, and a timestamp (optional).

      The timestamp is the version number of the data. It can be automatically generated or customized. If you do not specify this parameter, Tablestore automatically generates a timestamp. For more information, see Max versions and TTL.

      • The version number is calculated based on the number of milliseconds that have elapsed since 00:00:00 UTC on January 1, 1970.
      • If you choose to specify the version number, ensure that the version number is a 64-bit timestamp accurate to the millisecond within the valid version range.
    • You need only to set the name of the attribute column and the timestamp to delete a specified version of data in an attribute column.

      A timestamp is a 64-bit integer that indicates a specified version of data. Unit: milliseconds.

    • You need only to set the name of the attribute column to delete an attribute column.
      Note A row exists even if all attribute columns in the row are deleted. To delete a row, use the DeleteRow operation.
  • Examples

    The following code provides an example on how to update the data of a specified row:

    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);
        });
                        

    For the detailed sample code, visit UpdateRow@GitHub.

DeleteRow

You can call this operation to delete a row. If the specified row does not exist, no change is made to the table.

  • Operations
      /**
       * Delete a row of data.
       */
      deleteRow(params, callback) 
                        
  • Parameters
    Parameter Description
    tableName The name of the table.
    primaryKey The primary key of the row.
    Note The configured number and types of primary key columns must be consistent with the actual number and types of primary key columns of the table.
    condition You can use conditional update to set a row existence condition or columns-based conditions for the row. For more information, see Configure conditional update.
  • Examples

    The following code provides an example on how to delete a row from a table:

    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);
    });
    
                        

    For the detailed sample code, visit DeleteRow@GitHub.