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

Note In this example, pkValue represents the primary key column value. Specify pkValue as required.

Prerequisites

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

PutRow

You can call this operation to insert a row. If the row exists, the PutRow operation deletes all versions of data in all columns from the existing row and then inserts a new row.

  • 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 row existence conditions or column-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.
    column The attribute column of the row.
    • An attribute column is specified by parameters in the following sequence: the attribute column name, attribute column value (ColumnValue), attribute column value type (ColumnType, which is optional), and timestamp (optional).
    • You can set ColumnType to ColumnType.INTEGER, ColumnType.STRING, ColumnType.BINARY, ColumnType.BOOLEAN, or ColumnType.DOUBLE, which separately indicates INTEGER, STRING (a UTF-8 encoded string), BINARY, BOOLEAN, or DOUBLE. If you want to set the column value type to BINARY, you must set ColumnType to ColumnType.BINARY. If you want to use other types of column values, the setting of ColumnType is 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 Tablestore 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.
      • If you specify the version number, make sure that the version number is a 64-bit timestamp accurate to the millisecond within the valid version range.
  • Example 1

    The following code provides an example on how to write a row that contains 10 attribute columns and write one version of data for each column. The version number (timestamp) is generated by Tablestore.

    private static void putRow(SyncClient client, String pkValue) {
        // Construct the primary key. 
        PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
        primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
        PrimaryKey primaryKey = primaryKeyBuilder.build();
        // Specify the name of the table. 
        RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey);
    
        // Add attribute columns. 
        for (int i = 0; i < 10; i++) {
            rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(i)));
        }
    
        client.putRow(new PutRowRequest(rowPutChange));
    }
                        
  • Example 2

    The following code provides an example on how to write a row that contains 10 attribute columns and write three versions of data for each column. In this example, a custom version number (timestamp) is used.

    private static void putRow(SyncClient client, String pkValue) {
        // Construct the primary key. 
        PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
        primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
        PrimaryKey primaryKey = primaryKeyBuilder.build();
        // Specify the name of the table. 
        RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey);
    
        // Add attribute columns. 
        long ts = System.currentTimeMillis();
        for (int i = 0; i < 10; i++) {
            for (int j = 0; j < 3; j++) {
                rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
            }
        }
    
        client.putRow(new PutRowRequest(rowPutChange));
    }
                        
  • Example 3

    The following code provides an example on how to write a row that contains 10 attribute columns and write three versions of data for each column when the specified row does not exist. In this example, a custom version number (timestamp) is used.

    private static void putRow(SyncClient client, String pkValue) {
        // Construct the primary key. 
        PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
        primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
        PrimaryKey primaryKey = primaryKeyBuilder.build();
        // Specify the name of the table. 
        RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey);
    
        // Set a conditional update that expects the specified row not to exist. 
        rowPutChange.setCondition(new Condition(RowExistenceExpectation.EXPECT_NOT_EXIST));
    
        // Add attribute columns. 
        long ts = System.currentTimeMillis();
        for (int i = 0; i < 10; i++) {
            for (int j = 0; j < 3; j++) {
                rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
            }
        }
    
        client.putRow(new PutRowRequest(rowPutChange));
    }
                        
  • Example 4

    The following code provides an example on how to write a row that contains 10 attribute columns and write three versions of data for each column when the specified row exists and the value of Col0 is greater than 100. In this example, a custom version number (timestamp) is used.

    private static void putRow(SyncClient client, String pkValue) {
        // Construct the primary key. 
        PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
        primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
        PrimaryKey primaryKey = primaryKeyBuilder.build();
        // Specify the name of the table. 
        RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey);
    
        // Set a conditional update that expects the specified row to exist and the Col0 value of the row to be greater than 100. 
        Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
        condition.setColumnCondition(new SingleColumnValueCondition("Col0",
                SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100)));
        rowPutChange.setCondition(condition);
    
        // Add attribute columns. 
        long ts = System.currentTimeMillis();
        for (int i = 0; i < 10; i++) {
            for (int j = 0; j < 3; j++) {
                rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
            }
        }
    
        client.putRow(new PutRowRequest(rowPutChange));
    }
                        

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.
  • 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, if two columns col0 and col1 are included in columnsToGet, the system returns only the values of the two columns.
    • If you use columnsToGet and filter together, the system first queries the columns specified by columnsToGet, and then returns rows that meet the filter conditions.
    maxVersions The maximum number of versions to read.
    Note You must set at least one of the following parameters: maxVersions and timeRange.
    • If only maxVersions is specified, data of the specified number of versions is returned starting from the latest version.
    • If only timeRange is specified, all data whose versions are within the specified time range or data of the specified version is returned.
    • If both maxVersions and timeRange are specified, data of the specified number of versions within the time range is returned starting from the latest version.
    timeRange The 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 only maxVersions is specified, data of the specified number of versions is returned starting from the latest version.
    • If only timeRange is specified, all data whose versions are within the specified time range or data of the specified version is returned.
    • If both maxVersions and timeRange are specified, data of the specified number of versions within the time range is returned starting from the latest version.
    • To query data within a range, you need to set start and end. start indicates the start timestamp. end indicates the end timestamp. The specified range includes the start value and excludes the end value.
    • To query data of a specific version number, you need to set timestamp. timestamp indicates a specified timestamp.

    You need only to set one of timestamp and [start, end).

    The timestamp value ranges from 0 to Long.MAX_VALUE. Unit: milliseconds.

    filter The filter used 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 you use columnsToGet and filter together, the system first queries the columns specified by columnsToGet, and then returns rows that meet the filter conditions.
  • Example 1

    The following code provides an example on how to read data of the latest version and the specified columns from a row:

    private static void getRow(SyncClient client, String pkValue) {
        // Construct the primary key. 
        PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
        primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
        PrimaryKey primaryKey = primaryKeyBuilder.build();
    
        // Specify the table name and primary key to read a row of data. 
        SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey);
        // Set MaxVersions to 1 to read the latest version of data. 
        criteria.setMaxVersions(1);
        GetRowResponse getRowResponse = client.getRow(new GetRowRequest(criteria));
        Row row = getRowResponse.getRow();
    
        System.out.println("Read complete. Result:");
        System.out.println(row);
    
        // Specify the columns to read. 
        criteria.addColumnsToGet("Col0");
        getRowResponse = client.getRow(new GetRowRequest(criteria));
        row = getRowResponse.getRow();
    
        System.out.println("Read complete. Result:");
        System.out.println(row);
    } 
  • Example 2

    The following code provides an example on how to read a row of data while a filter is used.

    private static void getRow(SyncClient client, String pkValue) {
        // Construct the primary key. 
        PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
        primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
        PrimaryKey primaryKey = primaryKeyBuilder.build();
    
        // Specify the table name and primary key to read a row of data. 
        SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey);
        // Set MaxVersions to 1 to read the latest version of data. 
        criteria.setMaxVersions(1);
    
        // Set a filter to return the row when the value in Col0 is 0. 
        SingleColumnValueFilter singleColumnValueFilter = new SingleColumnValueFilter("Col0",
                SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
        // If the Col0 column does not exist, the row is not returned. 
        singleColumnValueFilter.setPassIfMissing(false);
        criteria.setFilter(singleColumnValueFilter);
    
        GetRowResponse getRowResponse = client.getRow(new GetRowRequest(criteria));
        Row row = getRowResponse.getRow();
    
        System.out.println("Read complete. Result:"); ");
        System.out.println(row);
    }
  • Example 3

    The following code provides an example on how to read the data of the Col1 column in a row while a regular expression is used to filter data in the column.

    private static void getRow(SyncClient client, String pkValue) {
     
        SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName);
     
        // Construct the primary key. 
        PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
            .addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue))
            .build();
        criteria.setPrimaryKey(primaryKey);
     
        // Set MaxVersions to 1 to read the latest version of data. 
        criteria.setMaxVersions(1);
     
        // Set the filter. Data in the row is returned when cast<int>(regex(Col1) is greater than 100. 
        RegexRule regexRule = new RegexRule("t1:([0-9]+),", VariantType.Type.VT_INTEGER);
        SingleColumnValueRegexFilter filter =  new SingleColumnValueRegexFilter("Col1",
            regexRule,SingleColumnValueFilter.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100));
        criteria.setFilter(filter);
     
        GetRowResponse getRowResponse = client.getRow(new GetRowRequest(criteria));
        Row row = getRowResponse.getRow();
    
        System.out.println("Read complete. Result:"); ");
        System.out.println(row);
    }

UpdateRow

You can call this operation to update the 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 row does not exist, a new row is added.
Note If an UpdateRow operation only specifies columns to delete from a row and the row does not exist, no row is inserted into the table.
  • 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 row existence conditions or column-based conditions for the row. For more information, see Configure conditional update.
    column The attribute column to update.
    • An attribute column is specified by parameters in the following sequence: the attribute column name, attribute column value, attribute column value type (optional), and timestamp (optional).

      A timestamp is the data version number. You can customize a data version number or use the data version number generated by Tablestore. By default, if you do not specify this parameter, the data version number generated by Tablestore is used. For more information, see Max versions and TTL.

      • 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.
      • If you specify 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 specified version of data from an attribute column, you need only to set the attribute column name and timestamp.

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

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

    The following code provides an example on how to update columns, delete the data of the specified version from a column, and delete a specified column:

    private static void updateRow(SyncClient client, String pkValue) {
        // Construct the primary key. 
        PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
        primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
        PrimaryKey primaryKey = primaryKeyBuilder.build();
        // Specify the name of the table. 
        RowUpdateChange rowUpdateChange = new RowUpdateChange(TABLE_NAME, primaryKey);
    
        // Update columns. 
        for (int i = 0; i < 10; i++) {
            rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
        }
    
        // Delete a specified version of a column. 
        rowUpdateChange.deleteColumn("Col10", 1465373223000L);
    
        // Delete a column. 
        rowUpdateChange.deleteColumns("Col11");
    
        client.updateRow(new UpdateRowRequest(rowUpdateChange));
    }                   
  • Example 2

    The following code provides an example on how to set update conditions:

    private static void updateRow(SyncClient client, String pkValue) {
        // Construct the primary key. 
        PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
        primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
        PrimaryKey primaryKey = primaryKeyBuilder.build();
        // Specify the name of the table. 
        RowUpdateChange rowUpdateChange = new RowUpdateChange(TABLE_NAME, primaryKey);
    
        // Set a conditional update that expects the specified row to exist and the Col0 value of the row to be greater than 100. 
        Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
        condition.setColumnCondition(new SingleColumnValueCondition("Col0",
                SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100)));
        rowUpdateChange.setCondition(condition);
    
        // Update columns. 
        for (int i = 0; i < 10; i++) {
            rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
        }
    
        // Delete a specified version of a column. 
        rowUpdateChange.deleteColumn("Col10", 1465373223000L);
    
        // Delete a column. 
        rowUpdateChange.deleteColumns("Col11");
    
        client.updateRow(new UpdateRowRequest(rowUpdateChange));
    }             

DeleteRow

You can call this operation to delete a row. If the row to delete does not exist, the table remains unchanged.

  • 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 row existence conditions or columns-based conditions for the row. For more information, see Configure conditional update.
  • Example 1

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

    private static void deleteRow(SyncClient client, String pkValue) {
        // Construct the primary key. 
        PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
        primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
        PrimaryKey primaryKey = primaryKeyBuilder.build();
        // Specify the name of the table. 
        RowDeleteChange rowDeleteChange = new RowDeleteChange(TABLE_NAME, primaryKey);
    
        client.deleteRow(new DeleteRowRequest(rowDeleteChange));
    }                    
  • Example 2

    The following code provides an example on how to set deletion conditions:

    private static void deleteRow(SyncClient client, String pkValue) {
        // Construct the primary key. 
        PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
        primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
        PrimaryKey primaryKey = primaryKeyBuilder.build();
        // Specify the name of the table. 
        RowDeleteChange rowDeleteChange = new RowDeleteChange(TABLE_NAME, primaryKey);
    
        // Set a conditional update that expects a specified row to exist and the Col0 value of the row to be greater than 100. 
        Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
        condition.setColumnCondition(new SingleColumnValueCondition("Col0",
                SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100)));
        rowDeleteChange.setCondition(condition);
    
        client.deleteRow(new DeleteRowRequest(rowDeleteChange));
    }