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 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. |
const command = PokeTable.build(BatchWriteCommand)
.requests(...)
.options({
tableName: `tenant-${tenantId}-pokemons`
})
Execution
import { execute } from 'dynamodb-toolbox/table/actions/batchWrite'
await execute(...batchWriteCommands)
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):
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. |
- Capacity
- Metrics
- Document client
- Retries
const { ConsumedCapacity } = await execute(
{ capacity: 'TOTAL' },
...batchWriteCommands
)
const { ItemCollectionMetrics } = await execute(
{ metrics: 'SIZE' },
...batchWriteCommands
)
import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb'
const documentClient = new DynamoDBDocumentClient(...)
await execute(
{ documentClient },
...batchWriteCommands
)
const { Response } = await execute(
{ maxAttempts: 3 },
...batchGetCommands
)
Response
The data is returned using the same response syntax as the DynamoDB BatchWriteItem API.