AWS.DynamoDB reference

BatchExecuteStatement

Source: src/AWS/DynamoDB/BatchExecuteStatement.ts

Runtime binding for DynamoDB PartiQL BatchExecuteStatement.

The request is passed through unchanged, but IAM is scoped to the explicitly bound tables and their indexes.

BatchExecuteStatement: PartiQL

const batchExecuteStatement = yield* AWS.DynamoDB.BatchExecuteStatement(
  sourceTable,
  archiveTable,
);

const response = yield* batchExecuteStatement({
  Statements: [
    {
      Statement: `SELECT * FROM "${yield* sourceTable.tableName}" WHERE pk=?`,
      Parameters: [{ S: "user#1" }],
    },
  ],
});

BatchGetItem

Source: src/AWS/DynamoDB/BatchGetItem.ts

Runtime binding for dynamodb:BatchGetItem.

Bind this operation to one or more tables and key the request by each bound table’s LogicalId. The binding resolves those logical IDs to physical table names at runtime.

BatchGetItem: Reading Data

const batchGetItem = yield* BatchGetItem(sourceTable, archiveTable);

const response = yield* batchGetItem({
  RequestItems: {
    [sourceTable.LogicalId]: {
      Keys: [{ pk: { S: "user#1" }, sk: { S: "profile" } }],
    },
    [archiveTable.LogicalId]: {
      Keys: [{ pk: { S: "user#1" }, sk: { S: "profile" } }],
    },
  },
});

BatchWriteItem

Source: src/AWS/DynamoDB/BatchWriteItem.ts

Runtime binding for dynamodb:BatchWriteItem.

Bind this operation to one or more tables and key the request by each bound table’s LogicalId.

BatchWriteItem: Writing Data

const batchWriteItem = yield* AWS.DynamoDB.BatchWriteItem(sourceTable, archiveTable);

const response = yield* batchWriteItem({
  RequestItems: {
    [sourceTable.LogicalId]: [
      {
        PutRequest: {
          Item: {
            pk: { S: "user#1" },
            sk: { S: "profile" },
          },
        },
      },
    ],
  },
});

CreateBackup

Source: src/AWS/DynamoDB/CreateBackup.ts

Runtime binding for dynamodb:CreateBackup.

Bind this operation to a Table inside a function runtime to get a callable that creates an on-demand backup of the bound table, automatically injecting the table name. Provide the CreateBackupHttp layer on the Function to satisfy the binding.

CreateBackup: Backup and Restore

const createBackup = yield* AWS.DynamoDB.CreateBackup(table);

const response = yield* createBackup({ BackupName: "nightly" });
const backupArn = response.BackupDetails?.BackupArn;

DeleteBackup

Source: src/AWS/DynamoDB/DeleteBackup.ts

Runtime binding for dynamodb:DeleteBackup.

Bind this operation to a Table inside a function runtime to get a callable that deletes one of the bound table’s on-demand backups by ARN. The IAM grant covers every backup of the bound table ({tableArn}/backup/*). Provide the DeleteBackupHttp layer on the Function to satisfy the binding.

DeleteBackup: Backup and Restore

const deleteBackup = yield* AWS.DynamoDB.DeleteBackup(table);

const response = yield* deleteBackup({ BackupArn: backupArn });
const status = response.BackupDescription?.BackupDetails?.BackupStatus;

DeleteItem

Source: src/AWS/DynamoDB/DeleteItem.ts

Runtime binding for dynamodb:DeleteItem.

Bind this operation to a Table inside a function runtime to get a callable that deletes a single item by key, automatically injecting the table name. Provide the DeleteItemHttp layer on the Function to satisfy the binding.

DeleteItem: Writing Data

const deleteItem = yield* AWS.DynamoDB.DeleteItem(table);

yield* deleteItem({
  Key: {
    pk: { S: "user#123" },
    sk: { S: "profile" },
  },
});

DescribeBackup

Source: src/AWS/DynamoDB/DescribeBackup.ts

Runtime binding for dynamodb:DescribeBackup.

Bind this operation to a Table inside a function runtime to get a callable that reads the status and details of one of the bound table’s backups by ARN. The IAM grant covers every backup of the bound table ({tableArn}/backup/*). Provide the DescribeBackupHttp layer on the Function to satisfy the binding.

DescribeBackup: Backup and Restore

const describeBackup = yield* AWS.DynamoDB.DescribeBackup(table);

const response = yield* describeBackup({ BackupArn: backupArn });
const status = response.BackupDescription?.BackupDetails?.BackupStatus;

DescribeContinuousBackups

Source: src/AWS/DynamoDB/DescribeContinuousBackups.ts

Runtime binding for dynamodb:DescribeContinuousBackups.

Bind this operation to a Table inside a function runtime to get a callable that reads the bound table’s continuous-backup and point-in-time-recovery status (including the earliest and latest restorable times), automatically injecting the table name. Provide the DescribeContinuousBackupsHttp layer on the Function to satisfy the binding.

DescribeContinuousBackups: Backup and Restore

const describeContinuousBackups =
  yield* AWS.DynamoDB.DescribeContinuousBackups(table);

const response = yield* describeContinuousBackups();
const pitr =
  response.ContinuousBackupsDescription?.PointInTimeRecoveryDescription;

DescribeExport

Source: src/AWS/DynamoDB/DescribeExport.ts

Runtime binding for dynamodb:DescribeExport.

Bind this operation to a Table inside a function runtime to get a callable that reads the status of one of the bound table’s S3 exports by ARN. The IAM grant covers every export of the bound table ({tableArn}/export/*). Provide the DescribeExportHttp layer on the Function to satisfy the binding.

DescribeExport: Exporting to S3

const describeExport = yield* AWS.DynamoDB.DescribeExport(table);

const response = yield* describeExport({ ExportArn: exportArn });
const status = response.ExportDescription?.ExportStatus;

DescribeTable

Source: src/AWS/DynamoDB/DescribeTable.ts

Runtime binding for dynamodb:DescribeTable.

Bind this operation to a Table inside a function runtime to get a callable that reads the table’s metadata (key schema, indexes, status, throughput). Provide the DescribeTableHttp layer on the Function to satisfy the binding.

DescribeTable: Table Metadata

const describeTable = yield* AWS.DynamoDB.DescribeTable(table);

const response = yield* describeTable();
const status = response.Table?.TableStatus;

DescribeTimeToLive

Source: src/AWS/DynamoDB/DescribeTimeToLive.ts

Runtime binding for dynamodb:DescribeTimeToLive.

Bind this operation to a Table inside a function runtime to get a callable that reads the table’s TTL configuration. Provide the DescribeTimeToLiveHttp layer on the Function to satisfy the binding.

DescribeTimeToLive: Time to Live

const describeTimeToLive = yield* AWS.DynamoDB.DescribeTimeToLive(table);

const response = yield* describeTimeToLive();
const ttlStatus = response.TimeToLiveDescription?.TimeToLiveStatus;

ExecuteStatement

Source: src/AWS/DynamoDB/ExecuteStatement.ts

Runtime binding for DynamoDB PartiQL ExecuteStatement.

This binding scopes IAM to a specific table, but the statement text is still user-provided. Statements must only reference the bound table or its indexes.

ExecuteStatement: PartiQL

const executeStatement = yield* AWS.DynamoDB.ExecuteStatement(table);

const response = yield* executeStatement({
  Statement: `SELECT * FROM "${yield* table.tableName}" WHERE pk=?`,
  Parameters: [{ S: "user#1" }],
});

ExecuteTransaction

Source: src/AWS/DynamoDB/ExecuteTransaction.ts

Runtime binding for dynamodb:ExecuteTransaction.

Bind this operation to one or more tables inside a function runtime to get a callable that runs a PartiQL transaction. Statements reference the bound tables by their physical names (resolve them via table.tableName); the host is granted the transactional read/write actions on every bound table. Provide the ExecuteTransactionHttp layer on the Function to satisfy the binding.

ExecuteTransaction: PartiQL

const executeTransaction = yield* AWS.DynamoDB.ExecuteTransaction(table);
const tableName = yield* table.tableName;

yield* executeTransaction({
  TransactStatements: [
    {
      Statement: `UPDATE "${tableName}" SET balance = balance - 10 WHERE pk = ? AND sk = ?`,
      Parameters: [{ S: "account#1" }, { S: "balance" }],
    },
    {
      Statement: `UPDATE "${tableName}" SET balance = balance + 10 WHERE pk = ? AND sk = ?`,
      Parameters: [{ S: "account#2" }, { S: "balance" }],
    },
  ],
});

ExportTableToPointInTime

Source: src/AWS/DynamoDB/ExportTableToPointInTime.ts

Runtime binding for dynamodb:ExportTableToPointInTime.

Bind this operation to a Table and a destination S3 Bucket inside a function runtime to get a callable that starts a point-in-time export of the table to the bucket, automatically injecting the table ARN and bucket name. The table must have point-in-time recovery enabled. The deploy-time half grants the export action on the table plus the S3 write permissions the export requires on the bucket. Provide the ExportTableToPointInTimeHttp layer on the Function to satisfy the binding.

ExportTableToPointInTime: Exporting to S3

const exportTable = yield* AWS.DynamoDB.ExportTableToPointInTime(
  table,
  bucket,
);

const response = yield* exportTable({ ExportFormat: "DYNAMODB_JSON" });
const exportArn = response.ExportDescription?.ExportArn;

GetItem

Source: src/AWS/DynamoDB/GetItem.ts

Runtime binding for dynamodb:GetItem.

Bind this operation to a Table inside a function runtime to get a callable that automatically injects the table name.

GetItem: Reading Data

const getItem = yield* AWS.DynamoDB.GetItem(table);

const response = yield* getItem({
  Key: {
    pk: { S: "user#123" },
  },
});

ListBackups

Source: src/AWS/DynamoDB/ListBackups.ts

Runtime binding for dynamodb:ListBackups.

Bind this operation to a Table inside a function runtime to get a callable that lists the bound table’s on-demand backups, automatically injecting the table name. Provide the ListBackupsHttp layer on the Function to satisfy the binding.

ListBackups: Backup and Restore

const listBackups = yield* AWS.DynamoDB.ListBackups(table);

const response = yield* listBackups();
const backups = response.BackupSummaries;

ListExports

Source: src/AWS/DynamoDB/ListExports.ts

Runtime binding for dynamodb:ListExports.

Bind this operation to a Table inside a function runtime to get a callable that lists the bound table’s S3 exports, automatically injecting the table ARN. Provide the ListExportsHttp layer on the Function to satisfy the binding.

ListExports: Exporting to S3

const listExports = yield* AWS.DynamoDB.ListExports(table);

const response = yield* listExports();
const exports = response.ExportSummaries;

ListTables

Source: src/AWS/DynamoDB/ListTables.ts

Runtime binding for dynamodb:ListTables.

An account-level binding — call it with no arguments to get a callable that lists table names in the region. Provide the ListTablesHttp layer on the Function to satisfy the binding.

ListTables: Table Metadata

const listTables = yield* AWS.DynamoDB.ListTables();

const response = yield* listTables();
const tableNames = response.TableNames;

ListTagsOfResource

Source: src/AWS/DynamoDB/ListTagsOfResource.ts

Runtime binding for dynamodb:ListTagsOfResource.

Bind this operation to a Table inside a function runtime to get a callable that lists the table’s tags, automatically injecting the table ARN. Provide the ListTagsOfResourceHttp layer on the Function to satisfy the binding.

ListTagsOfResource: Table Metadata

const listTagsOfResource = yield* AWS.DynamoDB.ListTagsOfResource(table);

const response = yield* listTagsOfResource();
const tags = response.Tags;

PutItem

Source: src/AWS/DynamoDB/PutItem.ts

Runtime binding for dynamodb:PutItem.

Bind this operation to a Table inside a function runtime to get a callable that writes a single item, automatically injecting the table name and granting the host dynamodb:PutItem on the table. Provide the PutItemHttp layer on the Function to satisfy the binding.

PutItem: Writing Data

// inside the Function's Effect.gen, with Effect.provide(DynamoDB.PutItemHttp)
const putItem = yield* AWS.DynamoDB.PutItem(table);

yield* putItem({
  Item: {
    pk: { S: "user#123" },
    sk: { S: "profile" },
    name: { S: "Alice" },
  },
});

Query

Source: src/AWS/DynamoDB/Query.ts

Runtime binding for dynamodb:Query.

Bind this operation to a Table inside a function runtime to get a callable that queries items by key condition, automatically injecting the table name. Provide the QueryHttp layer on the Function to satisfy the binding.

Query: Reading Data

const query = yield* AWS.DynamoDB.Query(table);

const response = yield* query({
  KeyConditionExpression: "pk = :pk",
  ExpressionAttributeValues: { ":pk": { S: "user#123" } },
});
const items = response.Items;

RestoreTableFromBackup

Source: src/AWS/DynamoDB/RestoreTableFromBackup.ts

Runtime binding for dynamodb:RestoreTableFromBackup.

Bind this operation to a source and a target Table inside a function runtime to get a callable that restores one of the source table’s on-demand backups (by BackupArn) into the target, automatically injecting the target table name. Provide the RestoreTableFromBackupHttp layer on the Function to satisfy the binding.

RestoreTableFromBackup: Backup and Restore

const restoreTableFromBackup = yield* AWS.DynamoDB.RestoreTableFromBackup(
  sourceTable,
  restoreTargetTable,
);

const response = yield* restoreTableFromBackup({ BackupArn: backupArn });
const status = response.TableDescription?.TableStatus;

RestoreTableToPointInTime

Source: src/AWS/DynamoDB/RestoreTableToPointInTime.ts

Runtime binding for dynamodb:RestoreTableToPointInTime.

Bind this operation to a source and a target Table inside a function runtime to get a callable that restores the source’s point-in-time backup into the target, automatically injecting both table identifiers. The source table must have point-in-time recovery enabled. Provide the RestoreTableToPointInTimeHttp layer on the Function to satisfy the binding.

RestoreTableToPointInTime: Backup and Restore

const restore = yield* AWS.DynamoDB.RestoreTableToPointInTime(
  sourceTable,
  restoreTargetTable,
);

const response = yield* restore({
  UseLatestRestorableTime: true,
});
const status = response.TableDescription?.TableStatus;

Scan

Source: src/AWS/DynamoDB/Scan.ts

Runtime binding for dynamodb:Scan.

Bind this operation to a Table inside a function runtime to get a callable that scans the full table, automatically injecting the table name. Provide the ScanHttp layer on the Function to satisfy the binding.

Scan: Reading Data

const scan = yield* AWS.DynamoDB.Scan(table);

const response = yield* scan({});
const items = response.Items;
const count = response.Count;

TableEventSource

Source: src/AWS/DynamoDB/Stream.ts

Event source binding that subscribes a Lambda function to a DynamoDB table’s change stream. Enables the stream on the table (via the binding contract) and creates the Lambda event source mapping.

Prefer the consumeTableChanges helper for ergonomic use; provide the runtime-specific implementation layer (e.g. Lambda.TableEventSource) on the Function.

Table

Source: src/AWS/DynamoDB/Table.ts

An Amazon DynamoDB table with optional indexes, PITR, TTL, and stream-aware binding support.

Table owns the lifecycle of the physical table while the binding contract allows runtime-specific integrations such as Lambda table event sources to request stream configuration without forcing a circular input prop.

Table: Creating Tables

Basic Table

import * as DynamoDB from "alchemy/AWS/DynamoDB";

const table = yield* DynamoDB.Table("UsersTable", {
  partitionKey: "pk",
  attributes: {
    pk: "S",
  },
});

Table with Sort Key and TTL

const table = yield* DynamoDB.Table("SessionsTable", {
  partitionKey: "userId",
  sortKey: "sessionId",
  attributes: {
    userId: "S",
    sessionId: "S",
    expiresAt: "N",
  },
  timeToLiveSpecification: {
    Enabled: true,
    AttributeName: "expiresAt",
  },
});

Table with Global Secondary Index

const table = yield* DynamoDB.Table("OrdersTable", {
  partitionKey: "pk",
  sortKey: "sk",
  attributes: {
    pk: "S",
    sk: "S",
    gsi1pk: "S",
    gsi1sk: "S",
  },
  globalSecondaryIndexes: [{
    indexName: "GSI1",
    partitionKey: "gsi1pk",
    sortKey: "gsi1sk",
    projection: { ProjectionType: "ALL" },
  }],
});

Multi-Attribute GSI Keys

GSI partition and sort keys may be composed of up to four attributes each, indexing natural domain attributes directly instead of synthetic concatenated keys. Partition attributes are hashed together (queries must specify all of them with equality); sort attributes are queried left-to-right in declaration order.

const matches = yield* DynamoDB.Table("TournamentMatches", {
  partitionKey: "matchId",
  attributes: {
    matchId: "S",
    tournamentId: "S",
    region: "S",
    round: "S",
  },
  globalSecondaryIndexes: [{
    indexName: "TournamentRegionIndex",
    partitionKey: ["tournamentId", "region"],
    sortKey: ["round", "matchId"],
    projection: { ProjectionType: "ALL" },
  }],
});

// init
const query = yield* AWS.DynamoDB.Query(matches);

// runtime: query with every partition attribute, then narrow the sort
// attributes left-to-right
const response = yield* query({
  IndexName: "TournamentRegionIndex",
  KeyConditionExpression:
    "tournamentId = :t AND #r = :r AND round = :round",
  ExpressionAttributeNames: { "#r": "region" },
  ExpressionAttributeValues: {
    ":t": { S: "WINTER2024" },
    ":r": { S: "NA-EAST" },
    ":round": { S: "SEMIFINALS" },
  },
});

Table: Runtime Operations

Bind DynamoDB operations in the init phase and use them in runtime handlers. Bindings inject the table name and grant scoped IAM permissions automatically.

// init
const getItem = yield* AWS.DynamoDB.GetItem(table);
const putItem = yield* AWS.DynamoDB.PutItem(table);

return {
  fetch: Effect.gen(function* () {
    // runtime
    yield* putItem({
      Item: { pk: { S: "user#123" }, name: { S: "Alice" } },
    });
    const result = yield* getItem({
      Key: { pk: { S: "user#123" } },
    });
    return yield* HttpServerResponse.json(result.Item);
  }),
};

Table: Table Features

Resource Policy

const table = yield* DynamoDB.Table("SharedTable", {
  partitionKey: "pk",
  attributes: { pk: "S" },
  resourcePolicy: JSON.stringify({
    Version: "2012-10-17",
    Statement: [{
      Effect: "Allow",
      Principal: { AWS: "arn:aws:iam::111122223333:root" },
      Action: ["dynamodb:GetItem", "dynamodb:Query"],
      Resource: "*",
    }],
  }),
});

Kinesis Streaming Destination

import * as Kinesis from "alchemy/AWS/Kinesis";

const stream = yield* Kinesis.Stream("CdcStream", {});
const table = yield* DynamoDB.Table("CdcTable", {
  partitionKey: "pk",
  attributes: { pk: "S" },
  kinesisStreamingDestination: {
    streamArn: stream.streamArn,
    approximateCreationDateTimePrecision: "MICROSECOND",
  },
});

Contributor Insights

const table = yield* DynamoDB.Table("HotKeyTable", {
  partitionKey: "pk",
  attributes: { pk: "S" },
  contributorInsightsEnabled: true,
});

Table: DynamoDB Streams

Process change data capture events from a DynamoDB table using a Lambda event source mapping. The stream is enabled automatically through the binding contract.

// init
yield* DynamoDB.consumeTableChanges(
  table,
  { streamViewType: "NEW_AND_OLD_IMAGES" },
  Effect.fn(function* (record) {
    yield* Effect.log(`${record.eventName}: ${JSON.stringify(record.dynamodb)}`);
  }),
);

TableSink

Source: src/AWS/DynamoDB/TableSink.ts

A batching sink over DynamoDB BatchWriteItem (25 write requests / 16 MB per call). Entries the API echoes back in UnprocessedItems (throttling, internal errors) are re-submitted on a bounded schedule; exhausting retries fails the sink with a typed BatchRetryExhaustedError carrying the stranded entries.

Sinks are request-scoped consumers: acquire the sink during the Function’s init, drive it with Stream.run inside a handler, and let it drain fully before the handler returns.

TableSink: Streaming Writes

Stream Put Requests into a Table

const sink = yield* AWS.DynamoDB.TableSink(table);

yield* Stream.fromIterable(records).pipe(
  Stream.map((record): AWS.DynamoDB.TableSinkEntry => ({
    PutRequest: {
      Item: {
        pk: { S: record.pk },
        sk: { S: record.sk },
      },
    },
  })),
  Stream.run(sink),
);

Stream Delete Requests into a Table

yield* Stream.fromIterable(keys).pipe(
  Stream.map((key): AWS.DynamoDB.TableSinkEntry => ({
    DeleteRequest: {
      Key: {
        pk: { S: key.pk },
        sk: { S: key.sk },
      },
    },
  })),
  Stream.run(sink),
);

TransactGetItems

Source: src/AWS/DynamoDB/TransactGetItems.ts

Runtime binding for dynamodb:TransactGetItems.

Bind this operation to one or more tables and identify each table in the request with the bound table’s LogicalId.

TransactGetItems: Reading Data

const transactGetItems = yield* AWS.DynamoDB.TransactGetItems(
  sourceTable,
  archiveTable,
);

const response = yield* transactGetItems({
  TransactItems: [
    {
      Get: {
        Table: sourceTable.LogicalId,
        Key: { pk: { S: "user#1" }, sk: { S: "profile" } },
      },
    },
  ],
});

TransactWriteItems

Source: src/AWS/DynamoDB/TransactWriteItems.ts

Runtime binding for dynamodb:TransactWriteItems.

Bind this operation to one or more tables and identify each item’s target table by the bound table’s LogicalId.

TransactWriteItems: Writing Data

const transactWriteItems = yield* AWS.DynamoDB.TransactWriteItems(
  sourceTable,
  archiveTable,
);

yield* transactWriteItems({
  TransactItems: [
    {
      Put: {
        Table: sourceTable.LogicalId,
        Item: { pk: { S: "user#1" }, sk: { S: "profile" } },
      },
    },
  ],
});

UpdateItem

Source: src/AWS/DynamoDB/UpdateItem.ts

Runtime binding for dynamodb:UpdateItem.

Bind this operation to a Table inside a function runtime to get a callable that applies an update expression to a single item, automatically injecting the table name. Provide the UpdateItemHttp layer on the Function to satisfy the binding.

UpdateItem: Writing Data

const updateItem = yield* AWS.DynamoDB.UpdateItem(table);

const response = yield* updateItem({
  Key: {
    pk: { S: "user#123" },
    sk: { S: "profile" },
  },
  UpdateExpression: "SET #name = :name",
  ExpressionAttributeNames: { "#name": "name" },
  ExpressionAttributeValues: { ":name": { S: "Alice" } },
  ReturnValues: "ALL_NEW",
});

UpdateTimeToLive

Source: src/AWS/DynamoDB/UpdateTimeToLive.ts

Runtime binding for dynamodb:UpdateTimeToLive.

Bind this operation to a Table inside a function runtime to get a callable that enables or disables TTL expiry on an attribute. Provide the UpdateTimeToLiveHttp layer on the Function to satisfy the binding.

UpdateTimeToLive: Time to Live

const updateTimeToLive = yield* AWS.DynamoDB.UpdateTimeToLive(table);

yield* updateTimeToLive({
  TimeToLiveSpecification: {
    AttributeName: "expiresAt",
    Enabled: true,
  },
});