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

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):

Examples

Tuple

const command = PokeTable.build(BatchGetCommand).requests(
  PokemonEntity.build(BatchGetRequest).key(pikachuKey),
  PokemonEntity.build(BatchGetRequest).key(charizardKey),
  ...
)

Array

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)

info

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.

Examples

Strongly consistent

const command = PokeTable.build(BatchGetCommand)
  .requests(...)
  .options({
    consistent: true
  })

Attributes

const command = PokeTable.build(BatchGetCommand)
  .requests(...)
  .options({
    attributes: ['name', 'type']
  })

Multitenant

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

Execution

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

await execute(...batchGetCommands)

caution

Only one BatchGetCommand per Table is supported.

Note that the commands can be provided as tuples or arrays (the output is typed accordingly):

Examples

Tuple

await execute(
  PokeTable.build(BatchGetCommand).requests(...),
  OtherTable.build(BatchGetCommand).requests(...),
  ...
)

Array

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.

Examples

Capacity

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

Document client

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

const documentClient = new DynamoDBDocumentClient(...)

const { Response } = await execute(
  { documentClient },
  ...batchGetCommands
)

Retries

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.

note

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.