GetTransaction

Builds a transaction to get an entity item, to be used within TransactGetItems operations.

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

import {
  GetTransaction,
  execute
} from 'dynamodb-toolbox/entity/actions/transactGet'

const pikachuTransac =
  PokemonEntity.build(GetTransaction).key(pikachuKey)

const params = pikachuTransac.params()

const ashTransac =
  TrainerEntity.build(GetTransaction).key(ashKey)

const { Responses } = await execute(
  pikachuTransac,
  ashTransac,
  ...otherTransacs
)

// 🙌 Correctly typed!
const [{ Item: pikachu }, { Item: ash }] = Responses

Request

.key(...)

(required)

The key of the item to get (i.e. attributes that are tagged as part of the primary key):

const request = PokemonEntity.build(GetTransaction).key({
  pokemonId: 'pikachu1'
})

You can use the KeyInputItem generic type to explicitly type an object as a GetTransaction key object:

import type { KeyInputItem } from 'dynamodb-toolbox/entity'

const key: KeyInputItem<typeof PokemonEntity> = {
  pokemonId: 'pikachu1'
}

const request =
  PokemonEntity.build(BatchGetRequest).key(key)

.options(...)

Provides additional options:

const transaction = PokemonEntity.build(GetTransaction)
  .key(...)
  .options({
    attributes: ["name", "level"]
  })

You can use the GetTransactionOptions type to explicitly type an object as a GetTransaction options object:

import type { GetTransactionOptions } from 'dynamodb-toolbox/entity/actions/transactGet'

const options: GetTransactionOptions<typeof PokemonEntity> =
  { attributes: ['name', 'level'] }

const transaction = PokemonEntity.build(GetTransaction)
  .key(...)
  .options(options)

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

Option	Type	Default	Description
attributes	Path<Entity>[]	-	To specify a list of attributes to retrieve (improves performances but does not reduce costs). See the PathParser action for more details on how to write attribute paths.
tableName	string	-	Overrides the Table name. Mostly useful for multitenancy.

Examples

Attributes

const transaction = PokemonEntity.build(GetTransaction)
  .key({ pokemonId: 'pikachu1' })
  .options({
    attributes: ['type', 'level']
  })

Multitenant

const transaction = PokemonEntity.build(GetTransaction)
  .key({ pokemonId: 'pikachu1' })
  .options({
    tableName: `tenant-${tenantId}-pokemons`
  })

Execution

import { execute } from 'dynamodb-toolbox/entity/actions/transactGet'

await execute(...getTransactions)

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

Examples

Tuple

await execute(
  PokemonEntity.build(GetTransaction).key(pikachuKey),
  TrainerEntity.build(GetTransaction).key(ashKey),
  ...
)

Array

const commands: (
  | GetTransaction<typeof PokemonEntity>
  | GetTransaction<typeof TrainerEntity>
)[] = [
  PokemonEntity.build(GetTransaction).key(pikachuKey),
  TrainerEntity.build(GetTransaction).key(ashKey),
  ...
]

await execute(...commands)

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, ...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 GetTransaction entity is used to execute the operation. Use this option to override this behavior.

Examples

Capacity

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

Document client

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

const documentClient = new DynamoDBDocumentClient(...)

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

Aborted

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

const { Response } = await execute(
  { abortSignal },
  ...getTransactions
)

// 👇 Aborts the command
abortController.abort()

Response

The data is returned using the same response syntax as the DynamoDB TransactGetItems API. If present, the returned items are formatted by their respective entities.