Batching

Use the BatchGet and BatchWrite commands to perform read and write batch operations in DynamoDB. These are the Document Builder commands for BatchGetItem and BatchWriteItem operations.

Batch Reads

The BatchGet command enables you to retrieve multiple items by primary key in a single operation:

const batchGet = new BatchGet({
  keys: [
    { userId: '123', todoId: '456' },
    { userId: '789', todoId: '101' },
  ],
});

const { items } = await todoEntity.send(batchGet);
console.log(items);

Consistent Reads

If you need the read to be strongly consistent for all items, you can set the consistent parameter to true:

const batchGet = new BatchGet({
  keys: [
    { userId: '123', todoId: '456' },
    { userId: '789', todoId: '101' },
  ],
  consistent: true,
});

const { items } = await todoEntity.send(batchGet);

Batch Projected Gets

Use the BatchProjectedGet command when you only need specific attributes from multiple items.

Due to the items being a subset of your entity schema, batch projected gets require you to provide a Zod schema defining the shape of the projected items.

const batchProjectedGet = new BatchProjectedGet({
  keys: [
    { userId: '123', todoId: '456' },
    { userId: '789', todoId: '101' },
  ],
  projection: ['title', 'completed'],
  projectionSchema: z.object({
    title: z.string(),
    completed: z.boolean(),
  }),
});

const { items } = await todoEntity.send(batchProjectedGet);
// items is typed as Array<{ title: string; completed: boolean; }>
console.log(items);

Batch Writes

The BatchWrite command enables you to put (create or replace) and/or delete multiple items in a single operation:

const batchWrite = new BatchWrite({
  items: [
    { userId: '123', todoId: '456', title: 'Take out the trash', completed: false },
    { userId: '789', todoId: '101', title: 'Buy groceries', completed: true },
  ],
  deletes: [
    { userId: '111', todoId: '222' },
  ],
});

Unprocessed Items

Both BatchGet and BatchWrite commands may return unprocessed keys or items if the operation exceeds provisioned throughput limits. You can retry these unprocessed items in subsequent batch operations.

BatchGet will return unprocessedKeys, while BatchWrite will return unprocessedPuts and unprocessedDeletes.

Batch Get Command Config

The BatchGet command expects the following input config:

{
  keys: Array<Partial<Schema>>;
  consistent?: boolean;
  skipValidation?: boolean;
  timeoutMs?: number;
  abortController?: AbortController;
  returnConsumedCapacity?: ReturnConsumedCapacity;
}

Property	Type	Description
`keys` (required)	`Array<Partial<Schema>>`	An array of primary keys for the items to retrieve. Each key should contain the attributes that make up the primary key. If using computed primary keys, only include the attributes used by your key builder functions.
`consistent?`	`boolean`	If set to true, DynamoDB will ensure a strongly consistent read for all items. Defaults to `false`.
`skipValidation?`	`boolean`	If set to true, schema validation is bypassed entirely. Defaults to `false`.
`timeoutMs?`	`number`	Number of milliseconds to wait before the operation times out and auto-cancels.
`abortController?`	`AbortController`	If you need to abort the commands operation, you can use the abort controller to signal cancellation.
`returnConsumedCapacity?`	`ReturnConsumedCapacity`	Determines the level of detail about provisioned throughput consumption that is returned in the response. Valid values are `TOTAL`, `INDEXES`, and `NONE`.

Batch Get Command Result

The BatchGet command returns the following result:

{
  items: Schema[];
  unprocessedKeys?: Array<Partial<Schema>>;
  responseMetadata?: ResponseMetadata;
  consumedCapacity?: ConsumedCapacity;
}

Property	Type	Description
`items`	`Schema[]`	An array of retrieved items. Will be an empty array if no items were found.
`unprocessedKeys?`	`Array<Partial<Schema>>`	If present, contains the keys that were not processed due to provisioned throughput limits. These keys can be used in a subsequent batch get request to retry retrieval.
`responseMetadata?`	`ResponseMetadata`	Metadata about the response from DynamoDB.
`consumedCapacity?`	`ConsumedCapacity`	Information about the capacity units consumed by the operation, if requested via the `returnConsumedCapacity` config.

Batch Projected Get Command Config

The BatchProjectedGet command expects the following input config:

{
  keys: Array<Partial<Schema>>;
  projection: string[];
  projectionSchema: ZodObject;
  consistent?: boolean;
  skipValidation?: boolean;
  timeoutMs?: number;
  abortController?: AbortController;
  returnConsumedCapacity?: ReturnConsumedCapacity;
}

Property	Type	Description
`keys` (required)	`Array<Partial<Schema>>`	An array of primary keys for the items to retrieve. Each key should contain the attributes that make up the primary key. If using computed primary keys, only include the attributes used by your key builder functions.
`projection` (required)	`string[]`	An array of attribute names to include in the returned items.
`projectionSchema` (required)	`ZodObject`	A Zod schema defining the shape of the projected items.
`consistent?`	`boolean`	If set to true, DynamoDB will ensure a strongly consistent read for all items. Defaults to `false`.
`skipValidation?`	`boolean`	If set to true, schema validation is bypassed entirely. Defaults to `false`.
`timeoutMs?`	`number`	Number of milliseconds to wait before the operation times out and auto-cancels.
`abortController?`	`AbortController`	If you need to abort the commands operation, you can use the abort controller to signal cancellation.
`returnConsumedCapacity?`	`ReturnConsumedCapacity`	Determines the level of detail about provisioned throughput consumption that is returned in the response. Valid values are `TOTAL`, `INDEXES`, and `NONE`.

Batch Projected Get Command Result

The BatchProjectedGet command returns the following result:

{
  items: ProjectionSchema[];
  unprocessedKeys?: Array<Partial<ProjectionSchema>>;
  responseMetadata?: ResponseMetadata;
  consumedCapacity?: ConsumedCapacity;
}

Property	Type	Description
`items`	`ProjectionSchema[]`	An array of retrieved items. Will be an empty array if no items were found. Unlike the standard `BatchGet`, items will be typed according to the provided projection schema.
`unprocessedKeys?`	`Array<Partial<ProjectionSchema>>`	If present, contains the keys that were not processed due to provisioned throughput limits. These keys can be used in a subsequent batch get request to retry retrieval.
`responseMetadata?`	`ResponseMetadata`	Metadata about the response from DynamoDB.
`consumedCapacity?`	`ConsumedCapacity`	Information about the capacity units consumed by the operation, if requested via the `returnConsumedCapacity` config.

Batch Write Command Config

The BatchWrite command expects the following input config:

{
  items?: Array<Schema>;
  deletes?: Array<Partial<Schema>>;
  returnItemCollectionMetrics?: ReturnItemCollectionMetrics;
  skipValidation?: boolean;
  timeoutMs?: number;
  abortController?: AbortController;
  returnConsumedCapacity?: ReturnConsumedCapacity;
}

At least one of items or deletes must be provided.

Property	Type	Description
`items`	`Array<Schema>`	An array of items to put (create or replace) in the table.
`deletes`	`Array<Partial<Schema>>`	An array of primary keys for items to delete from the table. Each key should contain the attributes that make up the primary key. If using computed primary keys, only include the attributes used by your key builder functions.
`returnItemCollectionMetrics`	`ReturnItemCollectionMetrics`	Determines whether item collection metrics are returned. Valid values are `SIZE` and `NONE`.
`skipValidation?`	`boolean`	If set to true, schema validation is bypassed entirely. Defaults to `false`.
`timeoutMs?`	`number`	Number of milliseconds to wait before the operation times out and auto-cancels.
`abortController?`	`AbortController`	If you need to abort the commands operation, you can use the abort controller to signal cancellation.
`returnConsumedCapacity?`	`ReturnConsumedCapacity`	Determines the level of detail about provisioned throughput consumption that is returned in the response. Valid values are `TOTAL`, `INDEXES`, and `NONE`.

Batch Write Command Result

The BatchWrite command returns the following result:

{
  unprocessedPuts?: Array<Schema>;
  unprocessedDeletes?: Array<Partial<Schema>>;
  itemColectionMetrics?: ItemCollectionMetrics;
  responseMetadata?: ResponseMetadata;
  consumedCapacity?: ConsumedCapacity;
}

Property	Type	Description
`unprocessedPuts?`	`Array<Schema>`	If present, contains the put items that were not processed due to provisioned throughput limits. These items can be used in a subsequent batch write request to retry the put operations.
`unprocessedDeletes?`	`Array<Partial<Schema>>`	If present, contains the delete keys that were not processed due to provisioned throughput limits. These keys can be used in a subsequent batch write request to retry the delete operations.
`itemColectionMetrics?`	`ItemCollectionMetrics`	Information about item collection metrics, if requested via `returnItemCollectionMetrics`.
`responseMetadata?`	`ResponseMetadata`	Metadata about the response from DynamoDB.
`consumedCapacity?`	`ConsumedCapacity`	Information about the capacity units consumed by the operation, if requested via the `returnConsumedCapacity` config.

Tree-shakable Imports

import { BatchGet } from 'dynamo-document-builder/commands/batch-get';
import { BatchProjectedGet } from 'dynamo-document-builder/commands/batch-projected-get';
import { BatchWrite } from 'dynamo-document-builder/commands/batch-write';