Read a range of data with the Tablestore .NET SDK - Tablestore

This topic describes how to read a range of data from Tablestore by using the .NET SDK.

Prerequisites

Methods

public GetRangeResponse GetRange(GetRangeRequest request)

Asynchronous method:

public Task<GetRangeResponse> GetRangeAsync(GetRangeRequest request)

GetRangeRequest parameters

Parameter	Type	Description
tableName (Required)	string	The name of the table.
inclusiveStartPrimaryKey (Required)	PrimaryKey	The start primary key of the range, including the names and values of the primary key columns. The returned data includes the start primary key. The number and types of primary keys must match those 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. `ColumnValue.INF_MIN` represents negative infinity and `ColumnValue.INF_MAX` represents positive infinity.
exclusiveEndPrimaryKey (Required)	PrimaryKey	The end primary key of the range, including the names and values of the primary key columns. The returned data excludes the end primary key. The number and types of primary keys must match those of the table. `ColumnValue.INF_MIN` represents negative infinity and `ColumnValue.INF_MAX` represents positive infinity.
direction (Required)	GetRangeDirection	The read direction. `GetRangeDirection.Forward`: Performs a forward read. `GetRangeDirection.Backward`: Performs a backward read.
limit (Optional)	int	The maximum number of rows to return. The value must be greater than 0. If the number of matching rows exceeds this value, the response includes the specified number of rows and a `NextPrimaryKey` value that you can use for the next request.
columnsToGet (Optional)	HashSet<string>	The columns to read. You can specify primary key columns or attribute columns. If omitted, the operation returns the entire row. If specified, the response includes only the primary key columns and any specified attribute columns that exist in a row.
condition (Optional)	IColumnCondition	The filter to apply to the rows. For more information, see Filter. If you set both `columnsToGet` and `condition`, Tablestore first applies the `condition` to filter rows. Then, from the matching rows, it returns only the columns specified in `columnsToGet`.

Code examples

The following code example shows how to read data from the test_table table where the primary key value is greater than row1.

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

    // Call the GetRange method to read rows.
    GetRangeRequest getRangeRequest = new GetRangeRequest("test_table", GetRangeDirection.Forward, inclusiveStartPrimaryKey, exclusiveEndPrimaryKey);
    GetRangeResponse getRangeResponse = client.GetRange(getRangeRequest);

    // Process the response.
    Console.WriteLine($"RequestId: {getRangeResponse.RequestID}");
    Console.WriteLine($"Read CU Cost: {getRangeResponse.ConsumedCapacityUnit.Read}");
    Console.WriteLine($"Write CU Cost: {getRangeResponse.ConsumedCapacityUnit.Write}");
    Console.WriteLine("Row Data: ");
    foreach (Row row in getRangeResponse.RowDataList)
    {
        Console.WriteLine(row);
    }
}
catch (Exception ex)
{
    Console.WriteLine($"Get Range failed, exception: {ex.Message}");
}

A single GetRange request can return a maximum of 5,000 rows or 4 MB of data. If more data matches the query range, the response includes a NextPrimaryKey value. To retrieve the remaining data, use this value as the inclusiveStartPrimaryKey in your next GetRange request. The following code shows how to use a loop to iterate through all matching rows.

while (true)
{
    // Call the GetRange method to read rows.
    GetRangeRequest getRangeRequest = new GetRangeRequest("test_table", GetRangeDirection.Forward, inclusiveStartPrimaryKey, exclusiveEndPrimaryKey);
    GetRangeResponse getRangeResponse = client.GetRange(getRangeRequest);

    // Process the response.
    Console.WriteLine($"RequestId: {getRangeResponse.RequestID}");
    Console.WriteLine($"Read CU Cost: {getRangeResponse.ConsumedCapacityUnit.Read}");
    Console.WriteLine($"Write CU Cost: {getRangeResponse.ConsumedCapacityUnit.Write}");
    Console.WriteLine("Row Data: ");
    foreach (Row row in getRangeResponse.RowDataList)
    {
        Console.WriteLine(row);
    }

    if (getRangeResponse.NextPrimaryKey != null)
    {
        inclusiveStartPrimaryKey = getRangeResponse.NextPrimaryKey;
    }
    else
    {
        break;
    }
}

You can also configure your query using the following settings.

Set the data 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 set excludes the end primary key.
PrimaryKey exclusiveEndPrimaryKey = new PrimaryKey()
{
    { "id", new ColumnValue("row1") }
};

// Call the GetRange method to read rows backward.
GetRangeRequest getRangeRequest = new GetRangeRequest("test_table", GetRangeDirection.Backward, inclusiveStartPrimaryKey, exclusiveEndPrimaryKey);

Specify the attribute columns to read.

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

// Call the GetRange method to read rows.
GetRangeRequest getRangeRequest = new GetRangeRequest("test_table", GetRangeDirection.Forward, inclusiveStartPrimaryKey, exclusiveEndPrimaryKey, columnsToGet, null);

Set the maximum number of rows to return.

int limit = 10;

// Call the GetRange method to read rows.
GetRangeRequest getRangeRequest = new GetRangeRequest("test_table", GetRangeDirection.Forward, inclusiveStartPrimaryKey, exclusiveEndPrimaryKey, null, limit);

Tablestore:Read a range of data

Prerequisites

Methods

Code examples

Related topics