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

const { Item } = await PokemonEntity.build(GetItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .options({
    consistent: true
  })
  .send()

Attributes

const { Item } = await PokemonEntity.build(GetItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .options({
    attributes: ['type', 'level']
  })
  .send()

Multitenant

const { Item } = await PokemonEntity.build(GetItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .options({
    tableName: `tenant-${tenantId}-pokemons`
  })
  .send()

Aborted

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

const { Item } = await PokemonEntity.build(GetItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .send({ abortSignal })

// 👇 Aborts the command
abortController.abort()

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: ... }