Page through results

Runs the sample. Generated for this page; it reads the connection string from the environment and first remakes the sample database from sample-schema.json.

using ArxSamples.DynamoDb;
using ArxSamples.DynamoDb.Operations.RetrieveMultiple.Basics;

// The connection string comes from the environment, never from the code (see "Configure the connection").
var connectionString = Environment.GetEnvironmentVariable("ARX_SAMPLES_DYNAMODB")
    ?? throw new InvalidOperationException("Set the ARX_SAMPLES_DYNAMODB environment variable to your Amazon DynamoDB connection string.");

var dbContext = new SampleContext(connectionString);

// Every run starts from the sample data: this deletes and makes again what sample-schema.json lists
// (save the file in the project folder, see Get started).
await dbContext.Direct.ResetAsync();

await new Basic2_PageThroughResults().RunAsync(dbContext);

The sample, as it is in the repository.

using ARX.SDK;
using ARX.SDK.DynamoDb.Services;
using ARX.SDK.Query;
using ARX.SDK.Services;

using static ArxSamples.DynamoDb.SampleOutput;

namespace ArxSamples.DynamoDb.Operations.RetrieveMultiple.Basics;

/// <summary>
/// Page through a partition with paging cookies, in three scenarios: the first page, the next pages from the cookie, and
/// a page number, which DynamoDB can't jump to.
/// </summary>
/// <remarks>
/// A page continues from where the last one ended: pass back the <c>PagingCookie</c> the page returned, with the same
/// query. <c>HasNextPage</c> is exact, and the cookie is null on the last page. DynamoDB can't count or skip, so a page
/// number above 1 and a total count are ARX8001.
/// </remarks>
public sealed class Basic2_PageThroughResults : ISample
{
    public string Name => "retrieve-multiple-basics-2-page-through-results";

    public string Title => "Page through results";

    public async Task RunAsync(SampleContext dbContext)
    {
        var orders = Enumerable.Range(1, 12).Select(i =>
        {
            var order = new ArxEntity("sales_order");
            order["customer_id"] = "C-D421";
            order["order_number"] = $"SO-D42{i:00}";
            order["status"] = "OPEN";
            order["ordered_on"] = "2026-11-08";
            return order;
        }).ToList();
        await dbContext.Service.CreateMultipleAsync(orders);

        var first = await Scenario1_TheFirstPageAsync(dbContext.Service);

        await Scenario2_TheNextPagesAsync(dbContext.Service, first);

        await Scenario3_APageNumberAsync(dbContext.Service);
    }

    private static ArxQueryExpression Query(ArxPagingInfo page)
    {
        var query = new ArxQueryExpression("sales_order");
        query.ColumnSet.AddColumns("order_number");
        query.Criteria.AddCondition("customer_id", ArxConditionOperator.Equal, "C-D421");
        query.PageInfo = page;
        return query;
    }

    /// <summary>1. Five orders, and the cookie for the rest.</summary>
    private static async Task<ArxEntityCollection> Scenario1_TheFirstPageAsync(ArxDynamoDbService service)
    {
        Step("1. The first page");

        var page = await service.RetrieveMultipleAsync(Query(new ArxPagingInfo { Count = 5 }));

        Show($"{string.Join(", ", page.Entities.Select(x => x["order_number"]))}; more: {page.HasNextPage}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "order_number" FROM "crm" WHERE "PK" = 'CUSTOMER#C-D421' AND begins_with("SK", 'ORDER#')
         * -- Expect: 12 items; the first page holds SO-D4201 to SO-D4205.
         * ===========================================================
         */
        return page;
    }

    /// <summary>2. Each page from the last one's cookie, until there is none.</summary>
    private static async Task Scenario2_TheNextPagesAsync(ArxDynamoDbService service, ArxEntityCollection page)
    {
        Step("2. The next pages");

        while (page.PagingCookie != null)
        {
            page = await service.RetrieveMultipleAsync(Query(new ArxPagingInfo { Count = 5, PagingCookie = page.PagingCookie }));
            Show($"{string.Join(", ", page.Entities.Select(x => x["order_number"]))}; more: {page.HasNextPage}");
        }

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "order_number" FROM "crm" WHERE "PK" = 'CUSTOMER#C-D421' AND "SK" > 'ORDER#SO-D4205'
         * -- Expect: 7 items, SO-D4206 to SO-D4212.
         * ===========================================================
         */
    }

    /// <summary>3. Page 3 straight away: ARX8001. Page with cookies.</summary>
    private static async Task Scenario3_APageNumberAsync(ArxDynamoDbService service)
    {
        Step("3. A page number");

        try
        {
            await service.RetrieveMultipleAsync(Query(new ArxPagingInfo { Count = 5, PageNumber = 3 }));
        }
        catch (ArxNotSupportedException exception)
        {
            ShowError(exception);
        }

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "order_number" FROM "crm" WHERE "PK" = 'CUSTOMER#C-D421' AND begins_with("SK", 'ORDER#')
         * -- Expect: 12 items (PartiQL pages by its own NextToken, never by number).
         * ===========================================================
         */
    }
}

  > 1. The first page
      SO-D4201, SO-D4202, SO-D4203, SO-D4204, SO-D4205; more: True
  > 2. The next pages
      SO-D4206, SO-D4207, SO-D4208, SO-D4209, SO-D4210; more: True
      SO-D4211, SO-D4212; more: False
  > 3. A page number
      caught ArxNotSupportedException: ARX8001 NotSupported: DynamoDB can't jump to page 3: it reads on from where the last page ended. Pass the previous page's PagingCookie (PageNumber 1).