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. |
- Attributes
- Multitenant
const transaction = PokemonEntity.build(GetTransaction)
.key({ pokemonId: 'pikachu1' })
.options({
attributes: ['type', 'level']
})
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):
- Tuple
- Array
await execute(
PokemonEntity.build(GetTransaction).key(pikachuKey),
TrainerEntity.build(GetTransaction).key(ashKey),
...
)
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:
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. |
- Capacity
- Document client
const { ConsumedCapacity } = await execute(
{ capacity: 'TOTAL' },
...getTransactions
)
import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb'
const documentClient = new DynamoDBDocumentClient(...)
const { Response } = await execute(
{ documentClient },
...getTransactions
)
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.