Skip to main content

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:

OptionTypeDefaultDescription
tableNamestring-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)
caution

Only one BatchWriteCommand per Table is supported.

Options

The execute function accepts an additional object as a first argument for operation-level options:

await execute(options, ...batchWriteCommands)

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

OptionTypeDefaultDescription
capacityCapacityOption"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".
metricsMetricsOption"NONE"Determines whether item collection metrics are returned.

Possible values are "NONE" and "SIZE".
documentClientDocumentClient-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.
maxAttemptsinteger ≥ 11A "meta" option provided by DynamoDB-Toolbox to retry failed requests in a single promise.

Note that Infinity is a valid (albeit dangerous) option.
Examples
const { ConsumedCapacity } = await execute(
{ capacity: 'TOTAL' },
...batchWriteCommands
)

Response

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