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

Note In the examples in this topic, 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 data table.
primaryKey The primary key of the row.
Note
  • The number and types of the primary key columns that you specify must be the same as the actual number and types of primary key columns in the data table.
  • If a primary key column is an auto-increment primary key column, you need to only 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 The condition that you want to configure to perform the PutRow operation. You can configure a row existence condition or a condition based on column values. 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.
  • The timestamp is the data version number. For more information, see Data versions and TTL.

    You can specify 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 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 milliseconds within the valid version range.

Examples

  • Example 1

    The following code provides an example on how to write a row that contains 10 attribute columns, each of which stores data of only one version. The version numbers (timestamps) are 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 data 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, each of which stores data of three versions. In this example, you need to specify the version numbers (timestamps).

    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 data 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, each of which stores data of three versions, when the specified row does not exist. In this example, you need to specify the version numbers (timestamps).

    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 data table. 
        RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey);
    
        // Specify a condition for the PutRow operation. In this example, data is inserted only when the specified row does not 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, each of which stores data of three versions, when the specified row exists and the value of the Col0 column is greater than 100. In this example, you need to specify the version numbers (timestamps).

    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 data table. 
        RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey);
    
        // Specify a condition for the PutRow operation. In this example, data is inserted only when the specified row exists and the value of the Col0 column is 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.

One of 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.

Parameters

Parameter Description
tableName The name of the data table.
primaryKey The primary key of the row.
Note The number and types of the primary key columns that you specify must be the same as the actual number and types of primary key columns in the data table.
columnsToGet The columns that you want to return. You can specify the names of primary key columns or attribute columns.

If you do not specify a column name, 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 return specific columns. For example, if col0 and col1 are added to columnsToGet, only the values of the col0 and col1 columns are returned.
  • If you configure columnsToGet and filter at the same time, Tablestore first queries the columns specified by columnsToGet, and then returns rows that meet the filter conditions.
maxVersions The maximum number of data versions that you want to read.
Note You must configure at least one of the following parameters: maxVersions and timeRange.
  • If only maxVersions is specified, data of up to the maximum number of versions is returned from the latest to the earliest.
  • If only timeRange is specified, all data whose versions are within the specified time range or data of the specified versions is returned.
  • If both maxVersions and timeRange are specified, data of up to the maximum number of versions within the time range is returned from the latest to the earliest.
timeRange The range of versions or specific versions that you want to read. For more information, see TimeRange.
Note You must configure at least one of the following parameters: maxVersions and timeRange.
  • If only maxVersions is specified, data of up to the maximum number of versions is returned from the latest to the earliest.
  • If only timeRange is specified, all data whose versions are within the specified time range or data of the specified versions is returned.
  • If both maxVersions and timeRange are specified, data of up to the maximum number of versions within the time range is returned from the latest to the earliest.
  • To query data whose versions are within a specified time range, you must set start and end. start indicates the start timestamp. end indicates the end timestamp. The specified range is a left-closed and right-open interval.
  • To query data of a specific version, you must configure timestamp. timestamp indicates a specified timestamp.

You need to only configure 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 query results on the server side. Only rows that meet the filter conditions are returned. For more information, see Configure a filter.
Note If you configure columnsToGet and filter at the same time, Tablestore first queries the columns specified by columnsToGet, and then returns rows that meet the filter conditions.

Examples

  • Example 1:

    The following code provides an example on how to read data of the latest version from the specified columns of 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);
    
        // Configure a filter to return a row in which the value of the Col0 column 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);
     
        // Configure a filter. A 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 data table.
primaryKey The primary key of the row.
Note The number and types of the primary key columns that you specify must be the same as the actual number and types of primary key columns in the data table.
condition The condition that you want to configure to perform the UpdateRow operation. You can configure a row existence condition or a condition based on column values. For more information, see Configure conditional update.
column The attribute column you want 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 specify 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 Data versions and TTL.

    • The version number generated by Tablestore is 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 milliseconds within the valid version range.
  • To delete a specified version of data from an attribute column, you need to only 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 to only 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.

Examples

  • 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 from a row:

    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 data 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 specify a condition for the UpdateRow operation:

    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 data table. 
        RowUpdateChange rowUpdateChange = new RowUpdateChange(TABLE_NAME, primaryKey);
    
        // Specify a condition for the UpdateRow operation. In this example, data is updated only when the specified row exists and the value of the Col0 column is 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 data table.
primaryKey The primary key of the row.
Note The number and types of the primary key columns that you specify must be the same as the actual number and types of primary key columns in the data table.
condition The condition that you want to configure to perform the DeleteRow operation. You can configure a row existence condition or a condition based on column values. For more information, see Configure conditional update.

Examples

  • Example 1

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

    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 data table. 
        RowDeleteChange rowDeleteChange = new RowDeleteChange(TABLE_NAME, primaryKey);
    
        client.deleteRow(new DeleteRowRequest(rowDeleteChange));
    }                    
  • Example 2

    The following code provides an example on how to specify a condition for the DeleteRow operation:

    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 data table. 
        RowDeleteChange rowDeleteChange = new RowDeleteChange(TABLE_NAME, primaryKey);
    
        // Specify a condition for the DeleteRow operation. In this example, a row is deleted only when the row exists and the value of the Col0 column is 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));
    }