How an update finds its item

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.Update.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_HowToFindTheItems().RunAsync(dbContext);

The sample, as it is in the repository.

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

using static ArxSamples.DynamoDb.SampleOutput;

namespace ArxSamples.DynamoDb.Operations.Update.Basics;

/// <summary>
/// How an update finds its item in DynamoDB, in four scenarios: an order by its id and its customer, by its key's
/// attributes, every order a query of the customer's partition finds, and a match no partition answers.
/// </summary>
/// <remarks>
/// DynamoDB writes an item by its full key. An order's key is its customer and its number, so its id alone isn't
/// enough: give the customer too. A match by other columns works when they give a partition key, of the table or an index:
/// ARX queries it, then updates each item found by its key, all or nothing (at most 100), each conditioned on still
/// matching. Without a partition it is ARX8001: a write never scans. When an attribute an index is keyed by changes (the status), give the index key's other attributes too (the date): ARX rewrites the index keys from them.
/// </remarks>
public sealed class Basic2_HowToFindTheItems : ISample
{
    public string Name => "update-basics-2-how-to-find-the-items";

    public string Title => "How an update finds its item";

    public async Task RunAsync(SampleContext dbContext)
    {
        var customer = new ArxEntity("customer");
        customer["customer_id"] = "C-D211";
        customer["name"] = "Tailspin Toys";
        await dbContext.Service.CreateAsync(customer);

        var orders = new[] { "SO-D211", "SO-D212" }.Select(number =>
        {
            var order = new ArxEntity("sales_order");
            order["customer_id"] = "C-D211";
            order["order_number"] = number;
            order["status"] = "OPEN";
            order["ordered_on"] = "2026-11-02";
            return order;
        }).ToList();
        await dbContext.Service.CreateMultipleAsync(orders);

        await Scenario1_ByIdAndCustomerAsync(dbContext.Service);

        await Scenario2_ByTheKeysAttributesAsync(dbContext.Service);

        await Scenario3_ThroughAQueryAsync(dbContext.Service);

        await Scenario4_NoPartitionAsync(dbContext.Service);
    }

    /// <summary>1. The id Create returned plus the customer: ship SO-D211 (with its date, so ARX rewrites the GSI1 keys).</summary>
    private static async Task Scenario1_ByIdAndCustomerAsync(ArxDynamoDbService service)
    {
        Step("1. By the id and the customer");

        var change = new ArxEntity("sales_order") { RecordId = ArxRecordId.Of("order_number", "SO-D211") };
        change["customer_id"] = "C-D211";
        change["status"] = "SHIPPED";
        change["ordered_on"] = "2026-11-02";

        await service.UpdateAsync(change);

        Show("SO-D211 shipped");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "status", "GSI1PK" FROM "crm" WHERE "PK" = 'CUSTOMER#C-D211' AND "SK" = 'ORDER#SO-D211'
         * -- Expect: 1 item, status "SHIPPED", GSI1PK "STATUS#SHIPPED".
         * ===========================================================
         */
    }

    /// <summary>2. ArxMatch.Columns naming exactly the key's attributes: the same thing, said explicitly.</summary>
    private static async Task Scenario2_ByTheKeysAttributesAsync(ArxDynamoDbService service)
    {
        Step("2. By the key's attributes");

        var change = new ArxEntity("sales_order");
        change["customer_id"] = "C-D211";
        change["order_number"] = "SO-D212";
        change["status"] = "CANCELLED";
        change["ordered_on"] = "2026-11-02";

        await service.UpdateAsync(change, new ArxUpdateOptions { Match = ArxMatch.Columns("customer_id", "order_number") });

        Show("SO-D212 cancelled");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "status" FROM "crm" WHERE "PK" = 'CUSTOMER#C-D211' AND "SK" = 'ORDER#SO-D212'
         * -- Expect: 1 item, status "CANCELLED".
         * ===========================================================
         */
    }

    /// <summary>3. Every order of the customer, through a query of its partition: each found order updated by its key.</summary>
    private static async Task Scenario3_ThroughAQueryAsync(ArxDynamoDbService service)
    {
        Step("3. Through a query");

        var change = new ArxEntity("sales_order");
        change["customer_id"] = "C-D211";
        change["priority"] = "high";

        int changed = await service.UpdateAsync(change, new ArxUpdateOptions { Match = ArxMatch.Columns("customer_id") });

        Show($"{changed} orders marked high priority");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "order_number", "priority" FROM "crm" WHERE "PK" = 'CUSTOMER#C-D211' AND begins_with("SK", 'ORDER#')
         * -- Expect: 2 items, SO-D211 and SO-D212, both priority "high".
         * ===========================================================
         */
    }

    /// <summary>4. Every order of a date: no partition key in the match, so ARX8001 rather than a scan.</summary>
    private static async Task Scenario4_NoPartitionAsync(ArxDynamoDbService service)
    {
        Step("4. No partition");

        var change = new ArxEntity("sales_order");
        change["ordered_on"] = "2026-11-02";
        change["priority"] = "low";

        try
        {
            await service.UpdateAsync(change, new ArxUpdateOptions { Match = ArxMatch.Columns("ordered_on") });
        }
        catch (ArxNotSupportedException exception)
        {
            ShowError(exception);
        }

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "order_number", "priority" FROM "crm" WHERE "PK" = 'CUSTOMER#C-D211' AND begins_with("SK", 'ORDER#')
         * -- Expect: 2 items, both still priority "high".
         * ===========================================================
         */
    }
}

  > 1. By the id and the customer
      SO-D211 shipped
  > 2. By the key's attributes
      SO-D212 cancelled
  > 3. Through a query
      2 orders marked high priority
  > 4. No partition
      caught ArxNotSupportedException: ARX8001 NotSupported: Update of 'sales_order' by Columns(ordered_on): DynamoDB finds items by a partition key, and these columns give neither the table's (customer_id) nor an index's. Match by the key, or by columns that include an index's partition key attributes.