Get

Use the Get command to retrieve single items from DynamoDB. This is the Document Builder command for a GetItem operation.

Basic Usage

Retrieve an item by its primary key.

const todoEntity = new DynamoEntity({
  table: parentTable,
  schema: z.object({
    todoId: z.string(),
    userId: z.string(),
    title: z.string(),
    completed: z.boolean(),
  }),
  partitionKey: todo => key('USER', todo.userId),
  sortKey: todo => key('TODO', todo.todoId),
});

const getCommand = new Get({
  key: {
    userId: '123',
    todoId: '456',
  },
});

const getResult = await todoEntity.send(getCommand);
console.log(getResult.item);

Consistent Reads

If you need the read to be strongly consistent, you can set the consistent parameter to true.

const getCommand = new Get({
  key: {
    userId: '123',
    todoId: '456',
  },
  consistent: true,
});

const getResult = await todoEntity.send(getCommand);

Projection Gets

Use the ProjectedGet command when you only need specific attributes from an item.

Due to the item being a subset of your entity schema, projection gets require you to provide a Zod schema defining the shape of the projected item.

const projectedGet = new ProjectedGet({
  key: {
    userId: '123',
    todoId: '456',
  },
  projection: ['title', 'completed'],
  projectionSchema: z.object({
    title: z.string(),
    completed: z.boolean(),
  }),
});

const result = await todoEntity.send(projectedGet);
// result.item is typed as { title: string; completed: boolean; } | undefined
console.log(result.item?.title);

Get Command Config

The Get command expects the following input config:

{
  key: Partial<Schema>;
  consistent?: boolean;
  skipValidation?: boolean;
  timeoutMs?: number;
  abortController?: AbortController;
  returnConsumedCapacity?: ReturnConsumedCapacity;
}

Property	Type	Description
`key` (required)	`Partial<Schema>`	The primary key of the item to retrieve. If using computed primary keys, only include the attributes used by your key builder functions. Otherwise this should be the attributes that make up the full primary key (partition key and sort key, if applicable).
`consistent?`	`boolean`	If set to true, DynamoDB will ensure a strongly consistent read. Defaults to `false`.
`skipValidation?`	`boolean`	If set to true, schema validation is bypassed entirely. Defaults to `false`.
`timeoutMs?`	`number`	Number of milliseconds to wait before the operation times out and auto-cancels.
`abortController?`	`AbortController`	If you need to abort the commands operation, you can use the abort controller to signal cancellation.
`returnConsumedCapacity?`	`ReturnConsumedCapacity`	Determines the level of detail about provisioned throughput consumption that is returned in the response. Valid values are `TOTAL`, `INDEXES`, and `NONE`.

Get Command Result

The Get command returns the following result:

{
  item?: Schema;
  responseMetadata?: ResponseMetadata;
  consumedCapacity?: ConsumedCapacity;
}

Property	Type	Description
`item?`	`Schema`	The retrieved item, or `undefined` if no item was found for the provided key.
`responseMetadata?`	`ResponseMetadata`	Metadata about the response from DynamoDB.
`consumedCapacity?`	`ConsumedCapacity`	Information about the capacity units consumed by the operation, if requested via the `returnConsumedCapacity` config.

Projected Get Command Config

The ProjectedGet command expects the following input config:

{
  key: Partial<Schema>;
  projection: string[];
  projectionSchema: ZodObject;
  consistent?: boolean;
  skipValidation?: boolean;
  timeoutMs?: number;
  abortController?: AbortController;
  returnConsumedCapacity?: ReturnConsumedCapacity;
}

Property	Type	Description
`key` (required)	`Partial<Schema>`	The primary key of the item to retrieve. If using computed primary keys, only include the attributes used by your key builder functions. Otherwise this should be the attributes that make up the full primary key (partition key and sort key, if applicable).
`projection` (required)	`string[]`	An array of attribute names to include in the returned item.
`projectionSchema` (required)	`ZodObject`	A Zod schema defining the shape of the projected item.
`consistent?`	`boolean`	If set to true, DynamoDB will ensure a strongly consistent read. Defaults to `false`.
`skipValidation?`	`boolean`	If set to true, schema validation is bypassed entirely. Defaults to `false`.
`timeoutMs?`	`number`	Number of milliseconds to wait before the operation times out and auto-cancels.
`abortController?`	`AbortController`	If you need to abort the commands operation, you can use the abort controller to signal cancellation.
`returnConsumedCapacity?`	`ReturnConsumedCapacity`	Determines the level of detail about provisioned throughput consumption that is returned in the response. Valid values are `TOTAL`, `INDEXES`, and `NONE`.

Projected Get Command Result

The ProjectedGet command returns the following result:

{
  item?: ProjectionSchema;
  responseMetadata?: ResponseMetadata;
  consumedCapacity?: ConsumedCapacity;
}

Property	Type	Description
`item?`	`ProjectionSchema`	The retrieved item, or `undefined` if no item was found for the provided key. Unlike the standard `Get`, this item will be typed according to the provided projection schema.
`responseMetadata?`	`ResponseMetadata`	Metadata about the response from DynamoDB.
`consumedCapacity?`	`ConsumedCapacity`	Information about the capacity units consumed by the operation, if requested via the `returnConsumedCapacity` config.

Tree-shakable Imports

import { Get } from 'dynamo-document-builder/commands/get';
import { ProjectedGet } from 'dynamo-document-builder/commands/projected-get';