Iteratively read data with the Tablestore .NET SDK - Tablestore

This topic explains how to use the .NET SDK to iteratively read data from Tablestore.

Prerequisites

Method

public IEnumerable<Row> GetRangeIterator(GetIteratorRequest request)

GetIteratorRequest includes the following parameters.

Parameter	Type	Description
tableName (Required)	string	The name of the table.
inclusiveStartPrimaryKey (Required)	PrimaryKey	The start primary key, which includes the names and values of the primary key columns. The results include the row that matches the start primary key. The number and types of primary key columns must match the schema of the table. For a forward read, the start primary key must be less than the end primary key. For a backward read, the start primary key must be greater than the end primary key. Use `ColumnValue.INF_MIN` to represent the infinite minimum value and `ColumnValue.INF_MAX` to represent the infinite maximum value.
exclusiveEndPrimaryKey (Required)	PrimaryKey	The end primary key, which includes the names and values of the primary key columns. The results do not include the row that matches the end primary key. The number and types of primary key columns must match the schema of the table. Use `ColumnValue.INF_MIN` to represent the infinite minimum value and `ColumnValue.INF_MAX` to represent the infinite maximum value.
direction (Required)	GetRangeDirection	The read direction. `GetRangeDirection.Forward`: Performs a forward read. `GetRangeDirection.Backward`: Performs a backward read.
consumedCapacityUnitCounter (Required)	CapacityUnit	An object that tracks the capacity units consumed by the operation.
limit (Optional)	int	The maximum number of rows to read. The value must be greater than 0.
columnsToGet (Optional)	HashSet<string>	The columns to read. You can specify primary key columns or attribute columns. If this parameter is not set, the entire row is returned. If set, any row that does not contain any of the specified columns is omitted from the results.
condition (Optional)	IColumnCondition	The filter condition. For more information, see Filter. When both `columnsToGet` and `condition` are specified, Tablestore retrieves the selected columns before applying the filter condition.

Sample code

The following code iteratively reads data from the test_table table, starting from the row with the primary key value "row1".

try
{
    // Set the start primary key.
    PrimaryKey inclusiveStartPrimaryKey = new PrimaryKey()
    {
        { "id", new ColumnValue("row1") }
    };
    // Set the end primary key. The result does not include the end primary key.
    PrimaryKey exclusiveEndPrimaryKey = new PrimaryKey()
    {
        { "id", ColumnValue.INF_MAX }
    };

    // Create a CapacityUnit object to track the capacity units consumed during iteration.
    CapacityUnit capacityUnit = new CapacityUnit(0, 0);

    // Create the request for the iterator.
    GetIteratorRequest getIteratorRequest = new GetIteratorRequest("test_table", GetRangeDirection.Forward, inclusiveStartPrimaryKey, exclusiveEndPrimaryKey, capacityUnit);

    // Call GetRangeIterator to get the iterator.
    IEnumerable<Row> iterator = client.GetRangeIterator(getIteratorRequest);
    foreach (var row in iterator)
    {
        Console.WriteLine(row);
    }
}
catch (Exception ex)
{
    Console.WriteLine($"Get range iterator failed, exception: {ex.Message}");
}

The following examples show how to set different parameters for iterative reads.

Set the read direction.

// Set the start primary key. For a backward read, the start primary key must be greater than the end primary key.
PrimaryKey inclusiveStartPrimaryKey = new PrimaryKey()
{
    { "id", ColumnValue.INF_MAX }
};
// Set the end primary key. The result does not include the end primary key.
PrimaryKey exclusiveEndPrimaryKey = new PrimaryKey()
{
    { "id", new ColumnValue("row1") }
};

// Create the request for the iterator and set the direction to backward.
GetIteratorRequest getIteratorRequest = new GetIteratorRequest("test_table", GetRangeDirection.Backward, inclusiveStartPrimaryKey, exclusiveEndPrimaryKey, capacityUnit);

Set the maximum number of rows to read.

int limit = 20;

// Create the request for the iterator.
GetIteratorRequest getIteratorRequest = new GetIteratorRequest("test_table", GetRangeDirection.Forward, inclusiveStartPrimaryKey, exclusiveEndPrimaryKey, capacityUnit, null, limit);

Specify the attribute columns to read.

HashSet<string> columnsToGet = new HashSet<string> { "col2" };

// Create the request for the iterator.
GetIteratorRequest getIteratorRequest = new GetIteratorRequest("test_table", GetRangeDirection.Forward, inclusiveStartPrimaryKey, exclusiveEndPrimaryKey, capacityUnit, columnsToGet);