BatchGetCommand
Groups one or several BatchGetRequest
from the Table
entities to execute a BatchGetItem operation.
BatchGetItem operations can affect multiple tables, so BatchGetCommands
do not have a .send(...)
method. Instead, they should be performed via the dedicated execute
function:
import {
BatchGetCommand,
execute
} from 'dynamodb-toolbox/table/actions/batchGet'
import { BatchGetRequest } from 'dynamodb-toolbox/entity/actions/batchGet'
const pokeCmd = PokeTable.build(BatchGetCommand).requests(
PokemonEntity.build(BatchGetRequest).key(pikachuKey),
PokemonEntity.build(BatchGetRequest).key(charizardKey)
)
const params = pokeCmd.params()
const otherCmd = OtherTable.build(BatchGetCommand).requests(
TrainerEntity.build(BatchGetRequest).key(ashKey)
)
const { Responses } = await execute(pokeCmd, otherCmd)
// 🙌 Correctly typed!
const [[pikachu, charizard], [ash]] = Responses
Note that batch operations are more efficient than running their equivalent commands in parallel, but do not reduce costs.
Request
.requests(...)
(required)
The BatchGetRequests
to execute.
Note that the requests can be provided as tuples or arrays (the output is typed accordingly):
- Tuple
- Array
const command = PokeTable.build(BatchGetCommand).requests(
PokemonEntity.build(BatchGetRequest).key(pikachuKey),
PokemonEntity.build(BatchGetRequest).key(charizardKey),
...
)
const requests: BatchGetRequest<typeof PokemonEntity>[] = [
PokemonEntity.build(BatchGetRequest).key(pikachuKey),
PokemonEntity.build(BatchGetRequest).key(charizardKey),
...
]
const command =
PokeTable.build(BatchGetCommand).requests(...requests)
.options(...)
Provides additional table-level options:
const command = PokeTable.build(BatchGetCommand).options({
consistent: true,
...
})
You can use the BatchGetCommandOptions
type to explicitly type an object as a BatchGetCommand
options object:
import type { BatchGetCommandOptions } from 'dynamodb-toolbox/table/actions/batchGet'
const batchGetOptions: BatchGetCommandOptions<
// 👇 Optional entities
[typeof PokemonEntity, typeof TrainerEntity]
> = {
consistent: true,
...
}
const command = PokeTable.build(BatchGetCommand)
.requests(...)
.options(batchGetOptions)
It is advised to provide requests
first as they constrain the options
type.
Available options (see the DynamoDB documentation for more details):
Option | Type | Default | Description |
---|---|---|---|
consistent | boolean | false | By default, read operations are eventually consistent (which improves performances and reduces costs). Set to true to use strongly consistent reads. |
attributes | string[] | - | To specify a list of attributes to retrieve (improves performances but does not reduce costs). Requires requests. Paths must be common to all requested entities. See the PathParser action for more details on how to write attribute paths. |
tableName | string | - | Overrides the Table name. Mostly useful for multitenancy. |
- Strongly consistent
- Attributes
- Multitenant
const command = PokeTable.build(BatchGetCommand)
.requests(...)
.options({
consistent: true
})
const command = PokeTable.build(BatchGetCommand)
.requests(...)
.options({
attributes: ['name', 'type']
})
const command = PokeTable.build(BatchGetCommand)
.requests(...)
.options({
tableName: `tenant-${tenantId}-pokemons`
})
Execution
import { execute } from 'dynamodb-toolbox/table/actions/batchGet'
await execute(...batchGetCommands)
Only one BatchGetCommand
per Table is supported.
Note that the commands can be provided as tuples or arrays (the output is typed accordingly):
- Tuple
- Array
await execute(
PokeTable.build(BatchGetCommand).requests(...),
OtherTable.build(BatchGetCommand).requests(...),
...
)
const commands: (
| BatchGetCommand<typeof PokeTable>
| BatchGetCommand<typeof OtherTable>
)[] = [
PokeTable.build(BatchGetCommand).requests(...),
OtherTable.build(BatchGetCommand).requests(...)
]
await execute(...commands)
Options
The execute
function accepts an additional object as a first argument for operation-level options:
await execute(options, ...batchGetCommands)
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" . |
documentClient | DocumentClient | - | By default, the documentClient attached to the Table of the first BatchGetCommand 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
- Document client
- Retries
const { ConsumedCapacity } = await execute(
{ capacity: 'TOTAL' },
...batchGetCommands
)
import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb'
const documentClient = new DynamoDBDocumentClient(...)
const { Response } = await execute(
{ documentClient },
...batchGetCommands
)
const { Response } = await execute(
{ maxAttempts: 3 },
...batchGetCommands
)
Response
The data is returned using the same response syntax as the DynamoDB BatchGetItem API, except for the Responses
property.
Instead of a map of arrays indexed by table name, DynamoDB-Toolbox returns an array of arrays, where each sub-array contains the items of a BatchGetCommand
. Both commands and items are returned in the same order they were provided, and items are formatted by their respective entities.
The official documentation states that "DynamoDB does not return items in any particular order", but DynamoDB-Toolbox handles the re-ordering for you 😘
This format is also better for type inference, as DynamoDB-Toolbox does not statically know your table names.