edit-icon download-icon

Multiple-row operations

Last Updated: Apr 08, 2018

The Table Store SDK provides the following multi-row operation interfaces: BatchGetRow, BatchWriteRow, GetRange, and GetRangeIterator.

BatchGetRow

Batch reads several data rows from one or more tables. It is essentially a set of multiple GetRow operations. Each operation is executed, returns results, and consumes capacity units independently.

Compared to the execution of a large number of GetRow operations, the BatchGetRow operation reduces the request response time and increases the data read rate.

API

  1. /// <summary>
  2. /// <para>Batch reads several data rows from one or more tables.</para>
  3. /// <para>The BatchGetRow operation is essentially a set of multiple GetRow operations. Each operation is executed, returns results, and consumes capacity units independently.</para>
  4. /// Compared to the execution of a large number of GetRow operations, the BatchGetRow operation reduces the request response time and increases the data read rate.
  5. /// </summary>
  6. /// <param name="request">Request instance</param>
  7. /// <returns>Response instance</returns>
  8. public BatchGetRowResponse BatchGetRow(BatchGetRowRequest request);
  9. /// <summary>
  10. /// Asynchronous form of BatchGetRow.
  11. /// </summary>
  12. public Task<BatchGetRowResponse> BatchGetRowAsync(BatchGetRowRequest request);

Example

Batch read 10 data rows.

  1. // Construct a batch-read request object, including the primary key values of the 10 rows
  2. List<PrimaryKey> primaryKeys = new List<PrimaryKey>();
  3. for (int i = 0; i < 10; i++)
  4. {
  5. PrimaryKey primaryKey = new PrimaryKey();
  6. primaryKey.Add("pk0", new ColumnValue(i));
  7. primaryKey.Add("pk1", new ColumnValue("abc"));
  8. primaryKeys.Add(primaryKey);
  9. }
  10. try
  11. {
  12. BatchGetRowRequest request = new BatchGetRowRequest();
  13. request.Add(TableName, primaryKeys);
  14. // Call BatchGetRow to read 10 data rows
  15. var response = otsClient.BatchGetRow(request);
  16. var tableRows = response.RowDataGroupByTable;
  17. var rows = tableRows[TableName];
  18. // Input the data of the rows. The input data is omitted here. For more information, see the GitHub link.
  19. // BatchGetRow may partially fail. Therefore, the status of each row must be checked. For more information, see the GitHub link.
  20. }
  21. catch (Exception ex)
  22. {
  23. // Execution fails if an exception is thrown, and an error message is printed.
  24. Console.WriteLine("Batch get row failed, exception:{0}", ex.Message);
  25. }

Note:

  • BatchGetRow supports filter using conditional statements.
  • Code details can be found at BatchGetRow@GitHub.

BatchWriteRow

BatchWriteRow inserts, modifies, or deletes several data rows in one or more tables. It is a set of multiple PutRow, UpdateRow, and DeleteRow operations. Each operation is executed, returns results independently, and consumes capacity units independently.

API

  1. /// <summary>
  2. /// <para>Batch inserts, modifies, or deletes several data rows in one or more tables.</para>
  3. /// <para>The BatchWriteRow operation is essentially a set of multiple PutRow, UpdateRow, and DeleteRow operations. Each operation is executed, returns results, and consumes capacity units independently.</para>
  4. /// <para>Compared to the execution of a large number of write operations, the BatchWriteRow operation reduces the request response time and increases the data write rate.</para>
  5. /// </summary>
  6. /// <param name="request">Request instance</param>
  7. /// <returns>Response instance</returns>
  8. public BatchWriteRowResponse BatchWriteRow(BatchWriteRowRequest request);
  9. /// <summary>
  10. /// Asynchronous row of BatchWriteRow
  11. /// </summary>
  12. /// <param name="request"></param>
  13. /// <returns></returns>
  14. public Task<BatchWriteRowResponse> BatchWriteRowAsync(BatchWriteRowRequest request);

Example

Batch import 100 data rows.

  1. // Construct a batch-import request object, including the primary key values of the 100 rows
  2. var request = new BatchWriteRowRequest();
  3. var rowChanges = new RowChanges();
  4. for (int i = 0; i < 100; i++)
  5. {
  6. PrimaryKey primaryKey = new PrimaryKey();
  7. primaryKey.Add("pk0", new ColumnValue(i));
  8. primaryKey.Add("pk1", new ColumnValue("abc"));
  9. // Define the attribute columns of the 100 rows
  10. UpdateOfAttribute attribute = new UpdateOfAttribute();
  11. attribute.AddAttributeColumnToPut("col0", new ColumnValue(0));
  12. attribute.AddAttributeColumnToPut("col1", new ColumnValue("a"));
  13. attribute.AddAttributeColumnToPut("col2", new ColumnValue(true));
  14. rowChanges.AddUpdate(new Condition(RowExistenceExpectation.IGNORE), primaryKey, attribute);
  15. }
  16. request.Add(TableName, rowChanges);
  17. try
  18. {
  19. // Call BatchWriteRow
  20. var response = otsClient.BatchWriteRow(request);
  21. var tableRows = response.TableRespones;
  22. var rows = tableRows[TableName];
  23. // Partial operations of BatchGetRow may fail; therefore, the status of each row must be checked. For more information, see the GitHub link.
  24. }
  25. catch (Exception ex)
  26. {
  27. // Execution fails if an exception is thrown, and an error message is printed.
  28. Console.WriteLine("Batch put row failed, exception:{0}", ex.Message);
  29. }

Note:

  • BatchWriteRow supports filter using conditional statements.
  • Code details can be found at BatchWriteRow@GitHub.

GetRange

Reads data in the specified primary key range.

API

  1. /// <summary>
  2. /// Get data from multiple rows in the specified range.
  3. /// </summary>
  4. /// <param name="request">Request instance</param>
  5. /// <returns>Response instance</returns>
  6. public GetRangeResponse GetRange(GetRangeRequest request);
  7. /// <summary>
  8. /// Asynchronous form of GetRange.
  9. /// </summary>
  10. /// <param name="request"></param>
  11. /// <returns></returns>
  12. public Task<GetRangeResponse> GetRangeAsync(GetRangeRequest request);

Example

Read data in the specified range.

  1. // Read all rows in the range from (0, INF_MIN) to (100, INF_MAX)
  2. var inclusiveStartPrimaryKey = new PrimaryKey();
  3. inclusiveStartPrimaryKey.Add("pk0", new ColumnValue(0));
  4. inclusiveStartPrimaryKey.Add("pk1", ColumnValue.INF_MIN);
  5. var exclusiveEndPrimaryKey = new PrimaryKey();
  6. exclusiveEndPrimaryKey.Add("pk0", new ColumnValue(100));
  7. exclusiveEndPrimaryKey.Add("pk1", ColumnValue.INF_MAX);
  8. try
  9. {
  10. // Constructs a read request object in the specified range
  11. var request = new GetRangeRequest(TableName, GetRangeDirection.Forward,
  12. inclusiveStartPrimaryKey, exclusiveEndPrimaryKey);
  13. var response = otsClient.GetRange(request);
  14. // Continue the read operation if only partial data is returned
  15. var rows = response.RowDataList;
  16. var nextStartPrimaryKey = response.NextPrimaryKey;
  17. while (nextStartPrimaryKey != null)
  18. {
  19. request = new GetRangeRequest(TableName, GetRangeDirection.Forward,
  20. nextStartPrimaryKey, exclusiveEndPrimaryKey);
  21. response = otsClient.GetRange(request);
  22. nextStartPrimaryKey = response.NextPrimaryKey;
  23. foreach (RowDataFromGetRange row in response.RowDataList)
  24. {
  25. rows.Add(row);
  26. }
  27. }
  28. // Output the data of the rows. The output data is omitted here. For more information, see the GitHub link.
  29. // Execution is successful if no exception is thrown.
  30. Console.WriteLine("Get range succeeded");
  31. }
  32. catch (Exception ex)
  33. {
  34. // Execution fails if an exception is thrown, and an error message is printed.
  35. Console.WriteLine("Get range failed, exception:{0}", ex.Message);
  36. }

Note:

  • GetRange supports filter using conditional statements.
  • Code details can be found at GetRange@GitHub.

GetRangeIterator

Gets the iterator in the specified range.

API

  1. /// <summary>
  2. /// Get data from multiple rows in the specified range. The system returns the iterator used to iterate through each data row.
  3. /// </summary>
  4. /// <param name="request"><see cref="GetIteratorRequest"/></param>
  5. /// <returns>Return the <see cref="RowDataFromGetRange"/> iterator.</returns>
  6. public IEnumerable<RowDataFromGetRange> GetRangeIterator(GetIteratorRequest request);

Example

Get an iterator.

  1. // Read all rows in the range from (0, "a") to (1000, "xyz")
  2. PrimaryKey inclusiveStartPrimaryKey = new PrimaryKey();
  3. inclusiveStartPrimaryKey.Add("pk0", new ColumnValue(0));
  4. inclusiveStartPrimaryKey.Add("pk1", new ColumnValue("a"));
  5. PrimaryKey exclusiveEndPrimaryKey = new PrimaryKey();
  6. exclusiveEndPrimaryKey.Add("pk0", new ColumnValue(1000));
  7. exclusiveEndPrimaryKey.Add("pk1", new ColumnValue("xyz"));
  8. // Construct a CapacityUnit to record the CUs consumed by iteration
  9. var cu = new CapacityUnit(0, 0);
  10. try
  11. {
  12. // Construct a GetIteratorRequest. Filter criteria are supported.
  13. var request = new GetIteratorRequest(TableName, GetRangeDirection.Forward, inclusiveStartPrimaryKey,
  14. exclusiveEndPrimaryKey, cu);
  15. var iterator = otsClient.GetRangeIterator(request);
  16. // Iterator that reads data in a traversal method
  17. foreach (var row in iterator)
  18. {
  19. // Processing logic
  20. }
  21. Console.WriteLine("Iterate row succeeded");
  22. }
  23. catch (Exception ex)
  24. {
  25. Console.WriteLine("Iterate row failed, exception:{0}", ex.Message);
  26. }

Note:

  • GetRangeIterator supports filter using conditional statements.
  • Code details can be found at GetRangeIterator@GitHub.
Thank you! We've received your feedback.