edit-icon download-icon

Single-row operations

Last Updated: Mar 27, 2018

Table Store provides the following single-row operation APIs:

  • PutRow
  • GetRow
  • UpdateRow
  • DeleteRow

PutRow

The PutRow API is used to insert a row of data. If this row already exists, it is overwritten.

When performing PutRow, you can use the Conditional Update function to set conditions for the existence of the row to be written or values in certain columns of the existing row. For more information, see Conditional Update.

Example 1

In this example, a row with 10 attribute columns is written, and one version for each column is entered. The version number (timestamp) is specified by the server.

  1. private static void putRow(SyncClient client, String pkValue) {
  2. // Build primary key.
  3. PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
  4. primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
  5. PrimaryKey primaryKey = primaryKeyBuilder.build();
  6. RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey);
  7. //Add attribute columns
  8. for (int i = 0; i < 10; i++) {
  9. rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(i)));
  10. }
  11. client.putRow(new PutRowRequest(rowPutChange));
  12. }

Example 2

In this example, a row with 10 attribute columns is written, and three versions for each column is entered. The version number (timestamp) is specified by the client.

  1. private static void putRow(SyncClient client, String pkValue) {
  2. // Build primary key.
  3. PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
  4. primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
  5. PrimaryKey primaryKey = primaryKeyBuilder.build();
  6. RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey);
  7. //Add attribute columns
  8. long ts = System.currentTimeMillis();
  9. for (int i = 0; i < 10; i++) {
  10. for (int j = 0; j < 3; j++) {
  11. rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
  12. }
  13. }
  14. client.putRow(new PutRowRequest(rowPutChange));
  15. }

Example 3

In this example, if no row exists, the data is written.

  1. private static void putRow(SyncClient client, String pkValue) {
  2. // Build primary key.
  3. PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
  4. primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
  5. PrimaryKey primaryKey = primaryKeyBuilder.build();
  6. RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey);
  7. // Expect the original row does not exist
  8. rowPutChange.setCondition(new Condition(RowExistenceExpectation.EXPECT_NOT_EXIST));
  9. //Add attribute columns
  10. long ts = System.currentTimeMillis();
  11. for (int i = 0; i < 10; i++) {
  12. for (int j = 0; j < 3; j++) {
  13. rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
  14. }
  15. }
  16. client.putRow(new PutRowRequest(rowPutChange));
  17. }

Example 4

In this example, the original row is expected to exist and to write data when the Col0 value is greater than 100.

  1. private static void putRow(SyncClient client, String pkValue) {
  2. // Build primary key.
  3. PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
  4. primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
  5. PrimaryKey primaryKey = primaryKeyBuilder.build();
  6. RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey);
  7. // Expect the original row to exist and write data when the Col0 value is greater than 100
  8. Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
  9. condition.setColumnCondition(new SingleColumnValueCondition("Col0",
  10. SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100)));
  11. rowPutChange.setCondition(condition);
  12. //Add attribute columns
  13. long ts = System.currentTimeMillis();
  14. for (int i = 0; i < 10; i++) {
  15. for (int j = 0; j < 3; j++) {
  16. rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
  17. }
  18. }
  19. client.putRow(new PutRowRequest(rowPutChange));
  20. }

GetRow

The single-row GetRow API is used to read a single row of data. It has the following parameters:

  • PrimaryKey: The primary key of the row to read. It is a required parameter.

  • ColumnsToGet: The set of columns to read. If not set, all columns are read.

  • MaxVersions: The maximum number of versions to read. At least one of the MaxVersions and TimeRange parameters must be set.

  • TimeRange: The range of version numbers to read. At least one of the MaxVersions and TimeRange parameters must be set.

  • Filter: The filters applied. Filters are used by the server to filter the read results again.

Example 1

In this example, the latest version of single row is read and the specific ColumnsToGet is set.

  1. private static void getRow(SyncClient client, String pkValue) {
  2. // Build primary key.
  3. PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
  4. primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
  5. PrimaryKey primaryKey = primaryKeyBuilder.build();
  6. // Read a row.
  7. SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey);
  8. // Set the latest version to be read.
  9. criteria.setMaxVersions(1);
  10. GetRowResponse getRowResponse = client.getRow(new GetRowRequest(criteria));
  11. Row row = getRowResponse.getRow();
  12. System.out.println("Read complete, result:");
  13. System.out.println(row);
  14. // Set the columns to read
  15. criteria.addColumnsToGet("Col0");
  16. getRowResponse = client.getRow(new GetRowRequest(criteria));
  17. row = getRowResponse.getRow();
  18. System.out.println("Read complete, result:");
  19. System.out.println(row);
  20. }

Example 2

In this example, a filter is set.

  1. private static void getRow(SyncClient client, String pkValue) {
  2. // Build primary key.
  3. PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
  4. primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
  5. PrimaryKey primaryKey = primaryKeyBuilder.build();
  6. // Read a row.
  7. SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey);
  8. // Set the latest version to be read.
  9. criteria.setMaxVersions(1);
  10. // Set the filter; when the Col0 value is 0, this row is returned.
  11. SingleColumnValueFilter singleColumnValueFilter = new SingleColumnValueFilter("Col0",
  12. SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
  13. // If the column Col0 does not exist, the data is not returned.
  14. singleColumnValueFilter.setPassIfMissing(false);
  15. criteria.setFilter(singleColumnValueFilter);
  16. GetRowResponse getRowResponse = client.getRow(new GetRowRequest(criteria));
  17. Row row = getRowResponse.getRow();
  18. System.out.println("Read complete, result:");
  19. System.out.println(row);
  20. }

UpdateRow

The UpdateRow API is used to update a single row of data. If no row exists, a new row is added.

The update operation includes write column, delete column, and delete column version operations.

When performing UpdateRow, you can use the Conditional Update function to set conditions for the existence of the row to be updated or values in certain columns of the existing row. For more information, see Conditional Update.

Example 1

In this example, several columns are updated, while a specified version of a specified column, and a specified column, are deleted.

  1. private static void updateRow(SyncClient client, String pkValue) {
  2. // Build primary key.
  3. PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
  4. primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
  5. PrimaryKey primaryKey = primaryKeyBuilder.build();
  6. RowUpdateChange rowUpdateChange = new RowUpdateChange(TABLE_NAME, primaryKey);
  7. // Update columns
  8. for (int i = 0; i < 10; i++) {
  9. rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
  10. }
  11. // Delete the specified version of the specified column
  12. rowUpdateChange.deleteColumn("Col10", 1465373223000L);
  13. // Delete specified column
  14. rowUpdateChange.deleteColumns("Col11");
  15. client.updateRow(new UpdateRowRequest(rowUpdateChange));
  16. }

Example 2

In this example, update conditions are set.

  1. private static void updateRow(SyncClient client, String pkValue) {
  2. // Build primary key.
  3. PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
  4. primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
  5. PrimaryKey primaryKey = primaryKeyBuilder.build();
  6. RowUpdateChange rowUpdateChange = new RowUpdateChange(TABLE_NAME, primaryKey);
  7. // Expect the original row to exist and update data when the Col0 value is greater than 100
  8. Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
  9. condition.setColumnCondition(new SingleColumnValueCondition("Col0",
  10. SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100)));
  11. rowUpdateChange.setCondition(condition);
  12. // Update columns
  13. for (int i = 0; i < 10; i++) {
  14. rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
  15. }
  16. // Delete the specified version of the specified column
  17. rowUpdateChange.deleteColumn("Col10", 1465373223000L);
  18. // Delete specified column
  19. rowUpdateChange.deleteColumns("Col11");
  20. client.updateRow(new UpdateRowRequest(rowUpdateChange));
  21. }

DeleteRow

The DeleteRow API is used to delete a single row.

When performing DeleteRow, you can use the Conditional Update function to set conditions for the existence of the row to be deleted or values in certain columns of the existing row. For more information, see Conditional Update.

Example 1

In this example, a row is deleted.

  1. private static void deleteRow(SyncClient client, String pkValue) {
  2. // Build primary key.
  3. PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
  4. primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
  5. PrimaryKey primaryKey = primaryKeyBuilder.build();
  6. RowDeleteChange rowDeleteChange = new RowDeleteChange(TABLE_NAME, primaryKey);
  7. client.deleteRow(new DeleteRowRequest(rowDeleteChange));
  8. }

Example 2

In this example, deletion conditions are set.

  1. private static void deleteRow(SyncClient client, String pkValue) {
  2. // Build primary key.
  3. PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
  4. primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
  5. PrimaryKey primaryKey = primaryKeyBuilder.build();
  6. RowDeleteChange rowDeleteChange = new RowDeleteChange(TABLE_NAME, primaryKey);
  7. // Expect the original row to exist and delete data when the Col0 value is greater than 100
  8. Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
  9. condition.setColumnCondition(new SingleColumnValueCondition("Col0",
  10. SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100)));
  11. rowDeleteChange.setCondition(condition);
  12. client.deleteRow(new DeleteRowRequest(rowDeleteChange));
  13. }
Thank you! We've received your feedback.