How a delete finds its items

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.Delete.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.Delete.Basics;

/// <summary>
/// How a delete finds its items in DynamoDB, in four scenarios: an order by its id and its customer, several orders by
/// their keys, the rest of a customer's orders through a query, and a match no partition answers.
/// </summary>
/// <remarks>
/// An item is deleted by its full key. An order's key is its customer and its number, so give both: the id and the
/// customer, or <c>ArxMatch.Columns</c> naming the key's attributes. Columns that give a partition key, of the table or
/// an index, are answered by a query: the items found are deleted by their keys, all or nothing (at most 100). Columns that
/// give no partition are ARX8001: a write never scans.
/// </remarks>
public sealed class Basic2_HowToFindTheItems : ISample
{
    public string Name => "delete-basics-2-how-to-find-the-items";

    public string Title => "How a delete finds its items";

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

        var orders = new[] { "SO-D311", "SO-D312", "SO-D313", "SO-D314" }.Select(number =>
        {
            var order = new ArxEntity("sales_order");
            order["customer_id"] = "C-D311";
            order["order_number"] = number;
            order["status"] = "CANCELLED";
            order["ordered_on"] = "2026-10-30";
            return order;
        }).ToList();
        await dbContext.Service.CreateMultipleAsync(orders);

        await Scenario1_ByIdAndCustomerAsync(dbContext.Service);

        await Scenario2_SeveralByTheirKeysAsync(dbContext.Service);

        await Scenario3_ThroughAQueryAsync(dbContext.Service);

        await Scenario4_NoPartitionAsync(dbContext.Service);
    }

    /// <summary>1. SO-D311: its id, and its customer for the partition.</summary>
    private static async Task Scenario1_ByIdAndCustomerAsync(ArxDynamoDbService service)
    {
        Step("1. By the id and the customer");

        var match = new ArxEntity("sales_order") { RecordId = ArxRecordId.Of("order_number", "SO-D311") };
        match["customer_id"] = "C-D311";

        int deleted = await service.DeleteAsync(match);

        Show($"{deleted} item deleted");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "SK" FROM "crm" WHERE "PK" = 'CUSTOMER#C-D311' AND "SK" = 'ORDER#SO-D311'
         * -- Expect: no items.
         * ===========================================================
         */
    }

    /// <summary>2. SO-D312 and SO-D313 by their key attributes, in one transaction.</summary>
    private static async Task Scenario2_SeveralByTheirKeysAsync(ArxDynamoDbService service)
    {
        Step("2. Several by their keys");

        var matches = new[] { "SO-D312", "SO-D313" }.Select(number =>
        {
            var match = new ArxEntity("sales_order");
            match["customer_id"] = "C-D311";
            match["order_number"] = number;
            return match;
        }).ToList();

        int deleted = await service.DeleteMultipleAsync(matches, new ArxDeleteOptions { Match = ArxMatch.Columns("customer_id", "order_number") });

        Show($"{deleted} items deleted");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "order_number" FROM "crm" WHERE "PK" = 'CUSTOMER#C-D311' AND begins_with("SK", 'ORDER#')
         * -- Expect: 1 item, SO-D314.
         * ===========================================================
         */
    }

    /// <summary>3. The customer's remaining orders, through a query of its partition: the profile in the same partition stays.</summary>
    private static async Task Scenario3_ThroughAQueryAsync(ArxDynamoDbService service)
    {
        Step("3. Through a query");

        var match = new ArxEntity("sales_order");
        match["customer_id"] = "C-D311";

        int deleted = await service.DeleteAsync(match, new ArxDeleteOptions { Match = ArxMatch.Columns("customer_id") });

        Show($"{deleted} item deleted");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "SK" FROM "crm" WHERE "PK" = 'CUSTOMER#C-D311'
         * -- Expect: 1 item, PROFILE: the customer itself isn't a sales_order.
         * ===========================================================
         */
    }

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

        var match = new ArxEntity("sales_order");
        match["ordered_on"] = "2026-10-30";

        try
        {
            await service.DeleteAsync(match, new ArxDeleteOptions { Match = ArxMatch.Columns("ordered_on") });
        }
        catch (ArxNotSupportedException exception)
        {
            ShowError(exception);
        }

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "order_number" FROM "crm" WHERE "ordered_on" = '2026-10-30'
         * -- Expect: no items: the orders of that date went in scenarios 1 to 3.
         * ===========================================================
         */
    }
}

  > 1. By the id and the customer
      1 item deleted
  > 2. Several by their keys
      2 items deleted
  > 3. Through a query
      1 item deleted
  > 4. No partition
      caught ArxNotSupportedException: ARX8001 NotSupported: Delete 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.