BatchWriteCommand

Groups one or several BatchPutRequest and BatchDeleteRequest from the Table entities to execute a BatchWriteItem operation.

BatchWriteItem operations can affect multiple tables, so BatchWriteCommands do not have a .send(...) method. Instead, they should be performed via the dedicated execute function:

import {
  BatchWriteCommand,
  execute
} from 'dynamodb-toolbox/table/actions/batchWrite'
import { BatchPutRequest } from 'dynamodb-toolbox/entity/actions/batchPut'
import { BatchDeleteRequest } from 'dynamodb-toolbox/entity/actions/batchDelete'

const pokeCmd = PokeTable.build(BatchWriteCommand).requests(
  PokemonEntity.build(BatchPutRequest).item(pikachu),
  PokemonEntity.build(BatchPutRequest).item(charizard)
)

const params = pokeCmd.params()

const ashCmd = OtherTable.build(BatchWriteCommand).requests(
  TrainerEntity.build(BatchDeleteRequest).key(ashKey)
)

await execute(pokeCmd, ashCmd)

note

Note that batch operations are more efficient than running their equivalent commands in parallel, but do not reduce costs.

Request

.requests(...)

(required)

The BatchPutRequests and BatchDeleteRequests to execute.

.options(...)

Provides additional table-level options:

const command = PokeTable.build(BatchWriteCommand).options({
  ...
})

You can use the BatchWriteCommandOptions type to explicitly type an object as a BatchWriteCommand options object:

import type { BatchWriteCommandOptions } from 'dynamodb-toolbox/table/actions/batchWrite'

const batchWriteOptions: BatchWriteCommandOptions= {
  ...
}

const command = PokeTable.build(BatchWriteCommand)
  .requests(...)
  .options(batchWriteOptions)

Available options:

Option	Type	Default	Description
tableName	string	-	Overrides the Table name. Mostly useful for multitenancy.

Examples

const command = PokeTable.build(BatchWriteCommand)
  .requests(...)
  .options({
    tableName: `tenant-${tenantId}-pokemons`
  })

Execution

import { execute } from 'dynamodb-toolbox/table/actions/batchWrite'

await execute(...batchWriteCommands)

warning

Only one BatchWriteCommand per Table is supported.

Options

The execute function accepts an additional object as a first argument for operation-level options, as well as DocumentClient options such as abortSignal:

await execute(options, ...batchWriteCommands)

Available options (see the DynamoDB documentation for more details):

Option	Type	Default	Description
capacity	CapacityOption	"NONE"	Determines the level of detail about provisioned or on-demand throughput consumption that is returned in the response. Possible values are "NONE", "TOTAL" and "INDEXES".
metrics	MetricsOption	"NONE"	Determines whether item collection metrics are returned. Possible values are "NONE" and "SIZE".
documentClient	DocumentClient	-	By default, the documentClient attached to the Table of the first BatchWriteCommand is used to execute the operation. Use this option to override this behavior.
maxAttempts	integer ≥ 1	1	A "meta" option provided by DynamoDB-Toolbox to retry failed requests in a single promise. Note that Infinity is a valid (albeit dangerous) option.

Examples

Capacity

const { ConsumedCapacity } = await execute(
  { capacity: 'TOTAL' },
  ...batchWriteCommands
)

Metrics

const { ItemCollectionMetrics } = await execute(
  { metrics: 'SIZE' },
  ...batchWriteCommands
)

Document client

import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb'

const documentClient = new DynamoDBDocumentClient(...)

await execute(
  { documentClient },
  ...batchWriteCommands
)

Retries

await execute({ maxAttempts: 3 }, ...batchWriteCommands)

Aborted

const abortController = new AbortController()
const abortSignal = abortController.signal

await execute({ abortSignal }, ...batchWriteCommands)

// 👇 Aborts the command
abortController.abort()

Response

The data is returned using the same response syntax as the DynamoDB BatchWriteItem API.