GetItemCommand
Performs a GetItem Operation on an entity item:
import { GetItemCommand } from 'dynamodb-toolbox/entity/actions/get'
const getItemCommand = PokemonEntity.build(GetItemCommand)
const params = getItemCommand.params()
await getItemCommand.send()
Request
.key(...)
(required)
The key of the item to get (i.e. attributes that are tagged as part of the primary key):
const { Item } = await PokemonEntity.build(GetItemCommand)
.key({ pokemonId: 'pikachu1' })
.send()
You can use the KeyInputItem
generic type to explicitly type an object as a GetItemCommand
key object:
import type { KeyInputItem } from 'dynamodb-toolbox/entity'
const key: KeyInputItem<typeof PokemonEntity> = {
pokemonId: 'pikachu1'
}
const { Item } = await PokemonEntity.build(GetItemCommand)
.key(key)
.send()
.options(...)
Provides additional options:
const { Item } = await PokemonEntity.build(GetItemCommand)
.key(...)
.options({
consistent: true,
attributes: ['type', 'level'],
...
})
.send()
You can use the GetItemOptions
type to explicitly type an object as a GetItemCommand
options object:
import type { GetItemOptions } from 'dynamodb-toolbox/entity/actions/get'
const options: PutItemOptions<typeof PokemonEntity> = {
consistent: true,
attributes: ['type', 'level'],
...
}
await PokemonEntity.build(GetItemCommand)
.key(...)
.options(options)
.send()
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 | 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. |
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" . |
tableName | string | - | Overrides the Table name. Mostly useful for multitenancy. |
Examples
- Consistent read
- Attributes
- Multitenant
const { Item } = await PokemonEntity.build(GetItemCommand)
.key({ pokemonId: 'pikachu1' })
.options({
consistent: true
})
.send()
const { Item } = await PokemonEntity.build(GetItemCommand)
.key({ pokemonId: 'pikachu1' })
.options({
attributes: ['type', 'level']
})
.send()
const { Item } = await PokemonEntity.build(GetItemCommand)
.key({ pokemonId: 'pikachu1' })
.options({
tableName: `tenant-${tenantId}-pokemons`
})
.send()
Response
The data is returned using the same response syntax as the DynamoDB GetItem API. If present, the returned item is formatted by the Entity.
You can use the GetItemResponse
type to explicitly type an object as a GetItemCommand
response object:
import type { GetItemResponse } from 'dynamodb-toolbox/entity/actions/get'
const getItemResponse: GetItemResponse<
typeof PokemonEntity,
// 👇 Optional options
{ attributes: ['type', 'level'] }
// 👇 Typed as Pick<Pokemon, 'type' | 'level'> | undefined
> = { Item: ... }