Tablestore SDKs provide 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 of data. If the row already exists, this operation deletes the existing row (all columns and all versions of the original row), and then writes data to the row.

  • API operation
      /**
       * 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 number and type of primary key columns configured must be consistent with those of primary key columns of the table.
    • When the primary key column is an auto-increment column, you need only to set the value of the auto-increment column to placeholders. For more information, see Configure an auto-increment primary key column.
    condition You can use conditional update to set row existence conditions or column-based conditions. For more information, see Configure conditional update.
    Note
    • RowExistenceExpectation.IGNORE indicates that new data is inserted into a row no matter whether the specified row exists. 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 column of the row.
    • Each item specifies the values in the following sequence: the attribute column name, attribute column value type (optional), attribute column value (ColumnValue), and timestamp (optional).
    • The timestamp is the version number of the data. For more information, see Max versions and TTL.

      You can customize a version number or specify that the system generates the version number. If the timestamp is not set, the version number is generated by the system.

      • The version number is calculated based on the number of milliseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.
      • When you choose to customize the version number, make sure 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 of 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.
  • API operation
      /**
       * 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 number and type of primary key columns configured must be consistent with those of primary key columns of the table.
    columnsToGet The set of columns to read. The column name can be the primary key column or attribute column.

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

    Note
    • If you query a row of data, the system returns the data in all columns of the row. You can set the columnsToGet parameter to read the data only in specified columns. If col0 and col1 are added to columnsToGet, only the values of the col0 and col1 columns are returned.
    • When columnsToGet and columnFilter are used at the same time, the columns specified by columnsToGet are returned. Then, the returned columns are filtered.
    maxVersions The maximum number of read versions.
    Note You must specify at least one of 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 within a range or a version of data 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 Reads data within a range of versions or a version of data. For more information, see TimeRange.
    Note You must specify at least one of 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 within a range or a version of data 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 indicates the start timestamp. endTime indicates the end timestamp. The time range is a left-closed and right-open interval, which is [startTime, endTime).
    • If you query data within a range of versions, set specificTime. specificTime specifies a specific timestamp.

    You can set one of specificTime and [startTime, endTime),

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

    columnFilter Filters the read results on the server side and returns only the rows of data that meet the conditions in the filter. For more information, see Configure a filter.
    Note When columnsToGet and columnFilter are used at the same time, the columns specified by columnsToGet are returned. Then, the returned columns are filtered.
  • 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 // 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 or delete attribute columns of a row, delete a specified version of data from an attribute column, or update the existing data in an attribute column. If the 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.
  • API operation
      /**
       * 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 number and type of primary key columns configured must be consistent with those of primary key columns of the table.
    condition You can use conditional update to set row existence conditions or column-based conditions. For more information, see Configure conditional update.
    updateOfAttributeColumns The attribute column to be updated.
    • To add or update data, you must set the attribute name, attribute value, attribute type (optional), and timestamp (optional).

      You can customize a version number or specify that the system generates the version number. If the timestamp is not set, the version number is generated by the system. 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.
      • When you choose to customize the version number, make sure that the version number is a 64-bit timestamp accurate to the millisecond within the valid version range.
    • To delete a specific version of an attribute, you need only to set the attribute name and timestamp.

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

    • When you delete an attribute column, you need only to set the attribute name.
      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 of data. If the row to delete does not exist, no changes are made to the table.

  • API operation
      /**
       * 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 number and type of primary key columns configured must be consistent with those of primary key columns of the table.
    condition You can use conditional update to set row existence conditions or column-based conditions. For more information, see Configure conditional update.
  • Examples

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

    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.