edit-icon download-icon

Single-row operations

Last Updated: Apr 08, 2018

The Table Store SDK provides the following single-row operation interfaces: PutRow, GetRow, UpdateRow, and DeleteRow.

PutRow

Inserts data into the specified row.

API

  1. /// <summary>
  2. /// Write a data row based on the specified table name, primary keys, and attributes. CapacityUnit consumed by the operation is returned.
  3. /// </summary>
  4. /// <param name="request">Data insertion request</param>
  5. /// <returns>CapacityUnit consumed by the operation</returns>
  6. public PutRowResponse PutRow(PutRowRequest request);
  7. /// <summary>
  8. /// Asynchronous form of PutRow
  9. /// </summary>
  10. public Task<PutRowResponse> PutRowAsync(PutRowRequest request);

Example 1

Insert a data row.

  1. // Define the primary keys of the row, which must be consistent with the primary keys defined in TableMeta during table creation
  2. var primaryKey = new PrimaryKey();
  3. primaryKey.Add("pk0", new ColumnValue(0));
  4. primaryKey.Add("pk1", new ColumnValue("abc"));
  5. // Define the attribute columns of the 100 rows
  6. var attribute = new AttributeColumns();
  7. attribute.Add("col0", new ColumnValue(0));
  8. attribute.Add("col1", new ColumnValue("a"));
  9. attribute.Add("col2", new ColumnValue(true));
  10. try
  11. {
  12. // Construct the request object for data insertion, with RowExistenceExpectation.IGNORE indicating that data is still inserted even when the specified row does not exist
  13. var request = new PutRowRequest("SampleTable", new Condition(RowExistenceExpectation.IGNORE),
  14. primaryKey, attribute);
  15. // Call PutRow to insert data
  16. otsClient.PutRow(request);
  17. // Execution is successful if no exception is thrown.
  18. Console.WriteLine("Put row succeeded.");
  19. }
  20. catch (Exception ex)
  21. {
  22. // Execution fails if an exception is thrown, and an error message is printed.
  23. Console.WriteLine("Put row failed, exception:{0}", ex.Message);
  24. }

Note:

  • Condition.IGNORE, Condition.EXPECT_EXIST, and Condition.EXPECT_NOT_EXIST are deprecated starting from v3.0.0. Use new Condition (RowExistenceExpectation.IGNORE), new Condition (RowExistenceExpectation.EXPECT_EXIST), and new Condition (RowExistenceExpectation.EXPECT_NOT_EXIST) instead.
  • RowExistenceExpectation.IGNORE indicates that new data is still inserted even when the specified row does not exist. If the inserted data is the same as the existing data, 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.
  • In addition to row conditions, the Condition parameter also supports column conditions starting from v2.2.0.
  • Code details could be obtained at PutRow@GitHub.

Example 2

Insert a data row based on specified conditions.

The following code example inserts data only when the specified row exists and the value of col1 is greater than 24.

  1. // Define the primary keys of the row, which must be consistent with the primary keys defined in TableMeta during table creation
  2. var primaryKey = new PrimaryKey();
  3. primaryKey.Add("pk0", new ColumnValue(0));
  4. primaryKey.Add("pk1", new ColumnValue("abc"));
  5. // Define the attribute columns of the 100 rows
  6. AttributeColumns attribute = new AttributeColumns();
  7. attribute.Add("col0", new ColumnValue(0));
  8. attribute.Add("col1", new ColumnValue("a"));
  9. attribute.Add("col2", new ColumnValue(true));
  10. var request = new PutRowRequest(tableName, new Condition(RowExistenceExpectation.EXPECT_EXIST),
  11. primaryKey, attribute);
  12. // When the value of col0 is greater than 24, PutRow is executed again to overwrite the original value.
  13. try
  14. {
  15. request.Condition.ColumnCondition = new RelationalCondition("col0",
  16. RelationalCondition.CompareOperator.GREATER_THAN,
  17. new ColumnValue(24));
  18. otsClient.PutRow(request);
  19. Console.WriteLine("Put row succeeded.");
  20. }
  21. catch (Exception ex)
  22. {
  23. Console.WriteLine("Put row failed. error:{0}", ex.Message);
  24. }

Note:

  • You can set a single condition or a combination of conditions. For example, you can set two conditions for data insertion as col1 > 5 and pk2 < ‘xyz’.
  • Attribute columns and primary key columns support the Condition parameter.
  • When the column specified in a condition does not exist in a row, PassIfMissing in RelationCondition controls the action to be taken. The default value is true.
  • Code details could be obtained at ConditionPutRow@GitHub.

Example 3

Insert a data row asynchronously.

  1. try
  2. {
  3. var putRowTaskList = new List<Task<PutRowResponse>>();
  4. for (int i = 0; i < 100; i++)
  5. {
  6. // Define the primary keys of the row, which must be consistent with the primary keys defined in TableMeta during table creation
  7. var primaryKey = new PrimaryKey();
  8. primaryKey.Add("pk0", new ColumnValue(i));
  9. primaryKey.Add("pk1", new ColumnValue("abc"));
  10. // Define the attribute columns of the 100 rows
  11. var attribute = new AttributeColumns();
  12. attribute.Add("col0", new ColumnValue(i));
  13. attribute.Add("col1", new ColumnValue("a"));
  14. attribute.Add("col2", new ColumnValue(true));
  15. var request = new PutRowRequest(TableName, new Condition(RowExistenceExpectation.IGNORE),
  16. primaryKey, attribute);
  17. putRowTaskList.Add(TabeStoreClient.PutRowAsync(request));
  18. }
  19. // Wait until each asynchronous call returns results and print the consumed CU
  20. for each (var task in putRowTaskList)
  21. {
  22. task.Wait();
  23. Console.WriteLine("consumed read:{0}, write:{1}", task.Result.ConsumedCapacityUnit.Read,
  24. task.Result.ConsumedCapacityUnit.Write);
  25. }
  26. // Data is inserted successfully if no exception is thrown.
  27. Console.WriteLine("Put row async succeeded.");
  28. }
  29. catch (Exception ex)
  30. {
  31. // An error message is printed if an exception is thrown.
  32. Console.WriteLine("Put row async failed. exception:{0}", ex.Message);
  33. }

Note:

  • Each asynchronous call starts a thread. A timeout error may occur if too many asynchronous calls are started consecutively and each call consumes an extended period of time.
  • Code details can be obtained at PutRowAsync@GitHub.

GetRow

Reads a single data row based on a given primary key.

API

  1. /// <summary>
  2. /// Read a single data row based on a given primary key.
  3. /// </summary>
  4. /// <param name="request">Data query request</param>
  5. /// <returns>Response returned by GetRow</returns>
  6. public GetRowResponse GetRow(GetRowRequest request);
  7. /// <summary>
  8. /// Asynchronous form of GetRow
  9. /// </summary>
  10. public Task<GetRowResponse> GetRowAsync(GetRowRequest request);

Example 1

Read a data row.

  1. // Define the primary keys of the row, which must be consistent with the primary keys defined in TableMeta during table creation
  2. PrimaryKey primaryKey = new PrimaryKey();
  3. primaryKey.Add("pk0", new ColumnValue(0));
  4. primaryKey.Add("pk1", new ColumnValue("abc"));
  5. try
  6. {
  7. // Construct a query request object. The entire row is read if no column is specified.
  8. var request = new GetRowRequest(TableName, primaryKey);
  9. // Call the GetRow interface to query data
  10. var response = otsClient.GetRow(request);
  11. // Output the data of the row. The output data is omitted here. For more information, see the GitHub link.
  12. // Data is read successfully if no exception is thrown.
  13. Console.WriteLine("Get row succeeded.");
  14. }
  15. catch (Exception ex)
  16. {
  17. // Execution fails if an exception is thrown, and an error message is printed.
  18. Console.WriteLine("Update table failed, exception:{0}", ex.Message);
  19. }

Note:

  • If you query a data row, the system returns the data in all columns of the row. You can use the columnsToGet parameter to read the data in specified columns. For example, the system only returns the data in col0 and col1 if col0 and col1 are inserted into columnsToGet.
  • Conditional filter is supported. For example, you can configure the system to return results only when the value of col0 is greater than 24.
  • When the columnsToGet and Condition parameters are both used, the system returns results first based on columnsToGet and then filters the returned columns based on the Condition parameter.
  • When a specified column does not exist, PassIfMissing determines the next action.
  • Code details could be obtained at GetRow@GitHub.

Example 2

Read a data row using the filter feature.

The following code example queries data and configures the system to return only the data in col0 and col1 and filter the data in col0 based on the condition that the value of col0 is 24.

  1. // Define the primary keys of the row, which must be consistent with the primary keys defined in TableMeta during table creation
  2. PrimaryKey primaryKey = new PrimaryKey();
  3. primaryKey.Add("pk0", new ColumnValue(0));
  4. primaryKey.Add("pk1", new ColumnValue("abc"));
  5. var rowQueryCriteria = new SingleRowQueryCriteria("SampleTable");
  6. rowQueryCriteria.RowPrimaryKey = primaryKey;
  7. // Condition 1: The value of col0 is 5.
  8. var filter1 = new RelationalCondition("col0",
  9. RelationalCondition.CompareOperator.EQUAL,
  10. new ColumnValue(5));
  11. // Condition 2: The value of col1 is not ff.
  12. var filter2 = new RelationalCondition("col1", RelationalCondition.CompareOperator.NOT_EQUAL, new ColumnValue("ff"));
  13. // Construct a combination of Condition 1 and Condition 2 with the OR relationship
  14. var filter = new CompositeCondition(CompositeCondition.LogicOperator.OR);
  15. filter.AddCondition(filter1);
  16. filter.AddCondition(filter2);
  17. rowQueryCriteria.Filter = filter;
  18. // Set the row you want to query based on the condition [col0,col1], and filter the queried data based on the specified condition
  19. rowQueryCriteria.AddColumnsToGet("col0");
  20. rowQueryCriteria.AddColumnsToGet("col1");
  21. // Construct GetRowRequest
  22. var request = new GetRowRequest(rowQueryCriteria);
  23. try
  24. {
  25. // Query data
  26. var response = otsClient.GetRow(request);
  27. // Output data or perform the related logical operation (omitted)
  28. // Execution is successful if no exception is thrown.
  29. Console.WriteLine("Get row with filter succeeded.");
  30. }
  31. catch (Exception ex)
  32. {
  33. // Execution fails if an exception is thrown, and an error message is printed.
  34. Console.WriteLine("Get row with filter failed, exception:{0}", ex.Message);
  35. }

Note: Code details could be obtained at GetRowWithFilter@GitHub.

UpdateRow

Updates 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.

API

  1. /// <summary>
  2. /// 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.
  3. /// </summary>
  4. /// <param name="request">Request instance</param>
  5. public UpdateRowResponse UpdateRow(UpdateRowRequest request);
  6. /// <summary>
  7. /// Asynchronous form of UpdateRow.
  8. /// </summary>
  9. /// <param name="request"></param>
  10. /// <returns></returns>
  11. public Task<UpdateRowResponse> UpdateRowAsync(UpdateRowRequest request);

Example

Update the data of the specified row.

  1. // Define the primary keys of the row, which must be consistent with the primary keys defined in TableMeta during table creation
  2. PrimaryKey primaryKey = new PrimaryKey();
  3. primaryKey.Add("pk0", new ColumnValue(0));
  4. primaryKey.Add("pk1", new ColumnValue("abc"));
  5. // Define the attribute columns of the 100 rows
  6. UpdateOfAttribute attribute = new UpdateOfAttribute();
  7. attribute.AddAttributeColumnToPut("col0", new ColumnValue(0));
  8. attribute.AddAttributeColumnToPut("col1", new ColumnValue("b")); // Change the original value 'a' to 'b'
  9. attribute.AddAttributeColumnToPut("col2", new ColumnValue(true));
  10. try
  11. {
  12. // Construct the request object for row updating, with RowExistenceExpectation.IGNORE indicating that data is still updated even when the specified row does not exist
  13. var request = new UpdateRowRequest(TableName, new Condition(RowExistenceExpectation.IGNORE),
  14. primaryKey, attribute);
  15. // Call the UpdateRow interface
  16. otsClient.UpdateRow(request);
  17. // Execution is successful if no exception is thrown.
  18. Console.Writeline("Update row succeeded.");
  19. }
  20. catch (Exception ex)
  21. {
  22. // Execution fails if an exception is thrown, and an error message is printed.
  23. Console.WriteLine("Update row failed, exception:{0}", ex.Message);
  24. }

Note:

  • Row updating supports the use of conditional statements.
  • Code details can be obtained at UpdateRow@GitHub.

DeleteRow

API

  1. /// <summary>
  2. /// Delete a data row based on the specified table name and primary keys.
  3. /// </summary>
  4. /// <param name="request">Request instance</param>
  5. /// <returns>Response instance</returns>
  6. public DeleteRowResponse DeleteRow(DeleteRowRequest request);
  7. /// <summary>
  8. /// Asynchronous form of DeleteRow.
  9. /// </summary>
  10. public Task<DeleteRowResponse> DeleteRowAsync(DeleteRowRequest request);

Example

Delete a data row.

  1. // The values of the primary key columns of the row to be deleted are 0 and "abc".
  2. var primaryKey = new PrimaryKey();
  3. primaryKey.Add("pk0", new ColumnValue(0));
  4. primaryKey.Add("pk1", new ColumnValue("abc"));
  5. try
  6. {
  7. // Construct a request, with Condition.EXPECT_EXIST indicating that the row is deleted only when it exists
  8. var deleteRowRequest = new DeleteRowRequest("SampleTable", Condition.EXPECT_EXIST, primaryKey);
  9. // Call the DeleteRow interface to delete the row
  10. otsClient.DeleteRow(deleteRowRequest);
  11. // The row is deleted successfully if no exception is thrown.
  12. Console.Writeline("Delete table succeeded.");
  13. }
  14. catch (Exception ex)
  15. {
  16. // The row fails to be deleted if an exception is thrown, and an error message is printed.
  17. Console.WriteLine("Delete table failed, exception:{0}", ex.Message);
  18. }

Note:

  • Row deletion supports the use of conditional statements.
  • Code details can obtained at DeleteRow@GitHub.
Thank you! We've received your feedback.