Retrieve one record

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.Retrieve.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 Basic1_RetrieveOneRecord().RunAsync(dbContext);

The sample, as it is in the repository.

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

using static ArxSamples.DynamoDb.SampleOutput;

namespace ArxSamples.DynamoDb.Operations.Retrieve.Basics;

/// <summary>
/// Read one item by its key, in three scenarios: a product by its id, an order by its full key with its customer read
/// back as a lookup, and an id no item has.
/// </summary>
/// <remarks>
/// One <c>GetItem</c>, strongly consistent by default (it sees every write that succeeded before it). An order's key is
/// its customer and its number, so give both. The catalog's lookup reads <c>customer_id</c> back as an
/// <see cref="ArxEntityReference"/>. Not found is null.
/// </remarks>
public sealed class Basic1_RetrieveOneRecord : ISample
{
    public string Name => "retrieve-basics-1-retrieve-one-record";

    public string Title => "Retrieve one record";

    public async Task RunAsync(SampleContext dbContext)
    {
        var product = new ArxEntity("product");
        product["sku"] = "SKU-D401";
        product["name"] = "Hiking pole";
        product["price"] = 34.50m;
        await dbContext.Service.CreateAsync(product);

        var order = new ArxEntity("sales_order");
        order["customer_id"] = "C-D401";
        order["order_number"] = "SO-D401";
        order["status"] = "OPEN";
        order["ordered_on"] = "2026-11-08";
        await dbContext.Service.CreateAsync(order);

        await Scenario1_ByIdAsync(dbContext.Service);

        await Scenario2_ByTheFullKeyAsync(dbContext.Service);

        await Scenario3_AnIdNoItemHasAsync(dbContext.Service);
    }

    /// <summary>1. A product by its SKU, the key and the id.</summary>
    private static async Task Scenario1_ByIdAsync(ArxDynamoDbService service)
    {
        Step("1. By id");

        ArxEntity? found = await service.RetrieveAsync("product", "SKU-D401");

        Show($"{found!["name"]}, {found["price"]}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "name", "price" FROM "product" WHERE "sku" = 'SKU-D401'
         * -- Expect: 1 item, Hiking pole, 34.5.
         * ===========================================================
         */
    }

    /// <summary>2. An order by its customer and number; its customer_id comes back as a reference.</summary>
    private static async Task Scenario2_ByTheFullKeyAsync(ArxDynamoDbService service)
    {
        Step("2. By the full key");

        var match = new ArxEntity("sales_order");
        match["customer_id"] = "C-D401";
        match["order_number"] = "SO-D401";

        ArxEntity? found = await service.RetrieveAsync(match);
        var customer = (ArxEntityReference)found!["customer_id"]!;

        Show($"{found["order_number"]}: {found["status"]}, customer {customer.EntityName} {customer.RecordId!.AsString()}");

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

    /// <summary>3. A SKU no item has: null.</summary>
    private static async Task Scenario3_AnIdNoItemHasAsync(ArxDynamoDbService service)
    {
        Step("3. An id no item has");

        ArxEntity? missing = await service.RetrieveAsync("product", "SKU-D499");

        Show($"found: {missing != null}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "sku" FROM "product" WHERE "sku" = 'SKU-D499'
         * -- Expect: no items.
         * ===========================================================
         */
    }
}

  > 1. By id
      Hiking pole, 34.5
  > 2. By the full key
      SO-D401: OPEN, customer customer C-D401
  > 3. An id no item has
      found: False