Move an item to a new key

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.AdvancedCases;

// 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 Advanced3_MoveToANewKey().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.AdvancedCases;

/// <summary>
/// Renumber an order: a new key for an item, in three scenarios: refused unless asked for, the move, and a move onto a
/// number another order has.
/// </summary>
/// <remarks>
/// DynamoDB can't change an item's key. An entity whose <c>RecordId</c> (the item it finds) and id attribute (the new id)
/// differ is ARX1001, unless <c>new ArxDynamoWriteOptions { AllowKeyChange = true }</c>: then ARX reads the item, applies
/// the change, puts it under its new key (keys, type and index keys written again) and deletes the old one, in one
/// transaction. A key that is taken is ARX3001, and nothing moves. A change someone else makes between the read and the
/// move is lost, unless the table has a version attribute (see "Detect a change made since the read"): then it is ARX2004.
/// </remarks>
public sealed class Advanced3_MoveToANewKey : ISample
{
    public string Name => "update-advanced-3-move-to-a-new-key";

    public string Title => "Move an item to a new key";

    private static readonly ArxDynamoWriteOptions AllowMove = new() { AllowKeyChange = true };

    public async Task RunAsync(SampleContext dbContext)
    {
        foreach (var (number, total) in new[] { ("SO-D261", 120m), ("SO-D269", 45m) })
        {
            var order = new ArxEntity("sales_order");
            order["customer_id"] = "C-D261";
            order["order_number"] = number;
            order["status"] = "OPEN";
            order["ordered_on"] = "2026-11-08";
            order["total"] = total;
            await dbContext.Service.CreateAsync(order);
        }

        await Scenario1_RefusedUnlessAskedForAsync(dbContext.Service);

        await Scenario2_TheMoveAsync(dbContext.Service);

        await Scenario3_OntoATakenNumberAsync(dbContext.Service);
    }

    private static ArxEntity Renumber(string from, string to)
    {
        var move = new ArxEntity("sales_order") { RecordId = ArxRecordId.Of("order_number", from) };
        move["customer_id"] = "C-D261";
        move["order_number"] = to;
        return move;
    }

    /// <summary>1. SO-D261 to SO-D262 without the option: ARX1001, nothing changes.</summary>
    private static async Task Scenario1_RefusedUnlessAskedForAsync(ArxDynamoDbService service)
    {
        Step("1. Refused unless asked for");

        try
        {
            await service.UpdateAsync(Renumber("SO-D261", "SO-D262"));
        }
        catch (ArxValidationException exception)
        {
            ShowError(exception);
        }

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

    /// <summary>2. The move, with a change on the way: SO-D261 becomes SO-D262, its total and index keys kept.</summary>
    private static async Task Scenario2_TheMoveAsync(ArxDynamoDbService service)
    {
        Step("2. The move");

        var move = Renumber("SO-D261", "SO-D262");
        move["note"] = "renumbered";

        await service.UpdateAsync(move, AllowMove);

        Show("SO-D261 is now SO-D262");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "SK", "total", "note", "GSI1PK" FROM "crm" WHERE "PK" = 'CUSTOMER#C-D261' AND begins_with("SK", 'ORDER#SO-D26')
         * -- Expect: 2 items: ORDER#SO-D262 (total 120, note "renumbered", GSI1PK "STATUS#OPEN") and ORDER#SO-D269.
         * ===========================================================
         */
    }

    /// <summary>3. SO-D262 onto SO-D269, which exists: ARX3001, and both orders stay as they were.</summary>
    private static async Task Scenario3_OntoATakenNumberAsync(ArxDynamoDbService service)
    {
        Step("3. Onto a taken number");

        try
        {
            await service.UpdateAsync(Renumber("SO-D262", "SO-D269"), AllowMove);
        }
        catch (ArxDatabaseException exception) when (exception.Code == ArxErrorCode.UniqueViolation)
        {
            ShowError(exception);
        }

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "SK", "total" FROM "crm" WHERE "PK" = 'CUSTOMER#C-D261' AND begins_with("SK", 'ORDER#SO-D26')
         * -- Expect: 2 items: ORDER#SO-D262 total 120 and ORDER#SO-D269 total 45.
         * ===========================================================
         */
    }
}

What every sample is given: the connection string (and the ISample interface the samples implement).

namespace ArxSamples.DynamoDb;

/// <summary>One documentation sample: a scenario a real application has, shown end to end.</summary>
public interface ISample
{
    /// <summary>The name to run it alone: <c>dotnet run -- &lt;name&gt;</c>.</summary>
    string Name { get; }

    /// <summary>One line on what it shows.</summary>
    string Title { get; }

    Task RunAsync(SampleContext dbContext);
}

/// <summary>
/// What a sample is given. Every sample gets the connection string; the application's service and catalog
/// (SampleContext.Application.cs) and the plain AWS SDK read-back helper (SampleContext.Direct.cs) live in their own
/// files, so a sample needs only the files it uses.
/// </summary>
public sealed partial class SampleContext
{
    public SampleContext(string connectionString)
    {
        ConnectionString = connectionString;
    }

    public string ConnectionString { get; }
}

How the samples print: Step for each scenario, Show for what it did, ShowError for an error caught on purpose.

using ARX.SDK;

namespace ArxSamples.DynamoDb;

/// <summary>How the samples print: a numbered step for each scenario, then what it did.</summary>
public static class SampleOutput
{
    /// <summary>The start of a scenario: <c>Step("1. By the id Create returned")</c>.</summary>
    public static void Step(string text) => Console.WriteLine($"  > {text}");

    /// <summary>What the scenario did.</summary>
    public static void Show(string text) => Console.WriteLine($"      {text}");

    /// <summary>An ARX error the scenario caught on purpose.</summary>
    public static void ShowError(ArxException exception)
        => Console.WriteLine($"      caught {exception.GetType().Name}: {exception.Message}");
}

The application's DynamoDB client, model, schema catalog and ARX service, created once and shared by the samples.

using Amazon.DynamoDBv2;
using Amazon.Runtime;
using ARX.SDK.DynamoDb.Model;
using ARX.SDK.DynamoDb.Services;
using ARX.SDK.Services;

namespace ArxSamples.DynamoDb;

/// <summary>The application's DynamoDB client, model, catalog and ARX service, shared by the samples.</summary>
public sealed partial class SampleContext
{
    private IAmazonDynamoDB? _client;
    private ArxDynamoModel? _model;
    private ArxSchemaCatalog? _catalog;
    private ArxDynamoDbService? _service;

    /// <summary>
    /// The DynamoDB client for the endpoint the connection string names. Credentials come from the AWS SDK's own chain
    /// (environment, profile, role), never from code; DynamoDB Local on this machine accepts any, so a local endpoint
    /// without credentials in the environment gets placeholder ones.
    /// </summary>
    public IAmazonDynamoDB Client => _client ??= CreateClient(ConnectionString);

    /// <summary>How the entities are laid out (SampleModel.cs).</summary>
    public ArxDynamoModel Model => _model ??= SampleModel.Build();

    /// <summary>The ids, lookups and selection sets (SampleModel.cs).</summary>
    public ArxSchemaCatalog Catalog => _catalog ??= SampleModel.Catalog();

    /// <summary>One service for the whole application: it holds no connection.</summary>
    public ArxDynamoDbService Service => _service ??= new ArxDynamoDbService(Client, Model, Catalog);

    private static IAmazonDynamoDB CreateClient(string endpoint)
    {
        var config = new AmazonDynamoDBConfig { ServiceURL = endpoint, AuthenticationRegion = Environment.GetEnvironmentVariable("AWS_REGION") ?? "us-east-1" };
        var local = Uri.TryCreate(endpoint, UriKind.Absolute, out var uri) && (uri.IsLoopback || uri.Host == "localhost");

        return local && Environment.GetEnvironmentVariable("AWS_ACCESS_KEY_ID") == null
            ? new AmazonDynamoDBClient(new BasicAWSCredentials("local", "local"), config)
            : new AmazonDynamoDBClient(config);
    }
}

How the application lays out its entities in Amazon DynamoDB, and its schema catalog.

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

namespace ArxSamples.DynamoDb;

/// <summary>
/// How the application lays out its entities in DynamoDB, in both designs, and its schema catalog.
/// </summary>
/// <remarks>
/// <para>
/// <b>A table per entity:</b> <c>product</c> has a table of its own, keyed by its <c>sku</c>; <c>lead</c> by its
/// <c>email</c>. The entity's attributes are the item's, keys included.
/// </para>
/// <para>
/// <b>A single table:</b> <c>crm</c> holds customers and their orders together. Each entity's keys are templates:
/// a customer is <c>PK = CUSTOMER#{customer_id}</c>, <c>SK = PROFILE</c>; an order shares its customer's partition,
/// <c>SK = ORDER#{order_number}</c>, so one query reads a customer with its orders. ARX writes the keys, the
/// <c>entity_type</c> attribute that tells the items apart, and the index keys (<c>GSI1</c>: orders by status and date).
/// </para>
/// <para>
/// <b>Write sharding:</b> <c>events</c> spreads the page views of one page over four partitions (a suffix from a hash of
/// the time), so a popular page doesn't overload one partition; ARX reads them back merged.
/// </para>
/// <para>
/// <b>The catalog</b> declares each entity's id (supplied: DynamoDB generates none, so ids come from the application),
/// the lookup from an order to its customer, the customer's display name and the order statuses.
/// </para>
/// </remarks>
public static class SampleModel
{
    public static ArxDynamoModel Build() => ArxDynamoModel.Create()
        .Table("product", partitionKey: "sku")
        .Table("lead", partitionKey: "email")
        .SingleTable("crm", "PK", "SK", crm => crm
            .Entity("customer", pk: "CUSTOMER#{customer_id}", sk: "PROFILE")
            .Entity("sales_order", pk: "CUSTOMER#{customer_id}", sk: "ORDER#{order_number}")
            .Index("GSI1", "GSI1PK", "GSI1SK")
            .EntityIndex("sales_order", "GSI1", pk: "STATUS#{status}", sk: "{ordered_on}"))
        .SingleTable("events", "PK", "SK", events => events
            .Entity("page_view", pk: "PAGE#{page}", sk: "VIEW#{viewed_at}"))
        .WriteSharding("page_view", shards: 4, by: "viewed_at")
        .Build();

    public static ArxSchemaCatalog Catalog() => ArxSchemaCatalog.Create()
        .Table("product", ArxIdColumn.Supplied<string>("sku"))
        .DisplayName("product", "name")
        .Table("lead", ArxIdColumn.Supplied<string>("email"))
        .Table("customer", ArxIdColumn.Supplied<string>("customer_id"))
        .DisplayName("customer", "name")
        .Table("sales_order", ArxIdColumn.Supplied<string>("order_number"))
        .Lookup("sales_order", "customer_id", "customer")
        .Table("page_view", ArxIdColumn.Supplied<string>("viewed_at"))
        .Add("OrderStatus", ArxSelectionSetKind.String, ("OPEN", "Open"), ("SHIPPED", "Shipped"), ("CANCELLED", "Cancelled"))
        .Build();
}

The plain AWSSDK.DynamoDBv2 read-back helper, for the samples that show what Amazon DynamoDB stored.

namespace ArxSamples.DynamoDb;

/// <summary>The plain AWS SDK outside ARX, for the samples that show what DynamoDB stored.</summary>
public sealed partial class SampleContext
{
    private DynamoDirectHelper? _direct;

    /// <summary>The plain AWS SDK outside ARX, used only to reset the tables and to show what was stored.</summary>
    public DynamoDirectHelper Direct => _direct ??= new DynamoDirectHelper(Client);
}

Plain AWSSDK.DynamoDBv2, not part of ARX: reads rows back so a sample can show what Amazon DynamoDB stored.

using System.Text.Json;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;

namespace ArxSamples.DynamoDb;

/// <summary>
/// The plain AWS SDK, outside ARX: it resets the sample tables from Schema/sample-schema.json and runs the PartiQL
/// statements of the samples' checks. Samples never write through it.
/// </summary>
public sealed class DynamoDirectHelper
{
    private readonly IAmazonDynamoDB _client;

    public DynamoDirectHelper(IAmazonDynamoDB client)
    {
        _client = client;
    }

    /// <summary>
    /// The sample schema: Schema/sample-schema.json next to the program (the samples' own project), or sample-schema.json
    /// in the project folder (a sample copied from its page, as Get started says).
    /// </summary>
    private static string SchemaPath()
    {
        var candidates = new[]
        {
            Path.Combine(AppContext.BaseDirectory, "Schema", "sample-schema.json"),
            Path.Combine(Directory.GetCurrentDirectory(), "sample-schema.json"),
            Path.Combine(Directory.GetCurrentDirectory(), "Schema", "sample-schema.json")
        };

        return candidates.FirstOrDefault(File.Exists)
            ?? throw new FileNotFoundException("sample-schema.json isn't in the project folder: download it from the Get started page and save it next to Program.cs.");
    }

    /// <summary>
    /// Deletes and creates every table sample-schema.json lists, with its keys and indexes; no other table is touched. It
    /// runs only against DynamoDB Local (a localhost endpoint): set ARX_SAMPLES_ALLOW_REMOTE_RESET=1 to reset the sample
    /// tables of a real AWS account deliberately.
    /// </summary>
    public async Task ResetAsync()
    {
        var endpoint = _client.Config.ServiceURL ?? string.Empty;
        var local = Uri.TryCreate(endpoint, UriKind.Absolute, out var uri) && (uri.IsLoopback || uri.Host.Equals("localhost", StringComparison.OrdinalIgnoreCase));

        if (!local && Environment.GetEnvironmentVariable("ARX_SAMPLES_ALLOW_REMOTE_RESET") != "1")
        {
            throw new InvalidOperationException(
                $"The samples reset their tables (delete and create them), and the client points at '{(endpoint.Length == 0 ? "AWS" : endpoint)}', not DynamoDB Local. "
                + "Point it at http://localhost:8000 (or your DynamoDB Local port), or set ARX_SAMPLES_ALLOW_REMOTE_RESET=1 to reset the sample tables there.");
        }

        using var schema = JsonDocument.Parse(await File.ReadAllTextAsync(SchemaPath()));

        foreach (var table in schema.RootElement.GetProperty("tables").EnumerateArray())
        {
            var name = table.GetProperty("name").GetString()!;

            try
            {
                await _client.DeleteTableAsync(name);
            }
            catch (ResourceNotFoundException)
            {
            }

            var definitions = new Dictionary<string, string>();
            var keys = Keys(table, definitions);
            var request = new CreateTableRequest { TableName = name, KeySchema = keys, BillingMode = BillingMode.PAY_PER_REQUEST };

            if (table.TryGetProperty("indexes", out var indexes))
            {
                request.GlobalSecondaryIndexes = indexes.EnumerateArray().Select(index => new GlobalSecondaryIndex
                {
                    IndexName = index.GetProperty("name").GetString(),
                    KeySchema = Keys(index, definitions),
                    Projection = new Projection { ProjectionType = ProjectionType.ALL }
                }).ToList();
            }

            request.AttributeDefinitions = definitions.Select(x => new AttributeDefinition(x.Key, x.Value)).ToList();
            await _client.CreateTableAsync(request);
        }
    }

    private static List<KeySchemaElement> Keys(JsonElement table, Dictionary<string, string> definitions)
    {
        var keys = new List<KeySchemaElement>();
        var pk = table.GetProperty("partitionKey").GetString()!;
        definitions[pk] = table.TryGetProperty("partitionKeyType", out var pkType) ? pkType.GetString()! : "S";
        keys.Add(new KeySchemaElement(pk, KeyType.HASH));

        if (table.TryGetProperty("sortKey", out var sk))
        {
            definitions[sk.GetString()!] = table.TryGetProperty("sortKeyType", out var skType) ? skType.GetString()! : "S";
            keys.Add(new KeySchemaElement(sk.GetString(), KeyType.RANGE));
        }

        return keys;
    }

    /// <summary>The items a PartiQL statement finds, as JSON, one line each.</summary>
    public async Task<IReadOnlyList<string>> QueryAsync(string statement)
    {
        var response = await _client.ExecuteStatementAsync(new ExecuteStatementRequest { Statement = statement, ConsistentRead = true });
        return response.Items.Select(item => JsonSerializer.Serialize(item.ToDictionary(x => x.Key, x => x.Value.S ?? x.Value.N ?? (x.Value.IsBOOLSet ? x.Value.BOOL.ToString() : "…")))).ToList();
    }
}

  > 1. Refused unless asked for
      caught ArxValidationException: ARX1001 InvalidArgument: Update of 'sales_order': the entity's RecordId and its 'order_number' differ, which would give the item a new key, and DynamoDB can't change a key in place. Pass new ArxDynamoWriteOptions { AllowKeyChange = true } to move it (the old item deleted and the new one put, in one transaction), or set only one of them.
  > 2. The move
      SO-D261 is now SO-D262
  > 3. Onto a taken number
      caught ArxDatabaseException: ARX3001 UniqueViolation: Update of 'sales_order': the new key: an item with the same key already exists. Nothing was written.