Put

Use the Put command to create or replace a single item in DynamoDB. This is the Document Builder command for a PutItem operation.

Basic Usage

Insert an item.

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 putCommand = new Put({
  item: {
    userId: '123',
    todoId: '456',
    title: 'Take out the trash',
    completed: false,
  },
});

await todoEntity.send(putCommand);

Returning the Previous Item

You can request that the put operation return the item’s attributes as they appeared before the put operation, in case you are overwriting an existing item. To do this, set the returnValues parameter in the command config.

const putCommand = new Put({
  item: {
    userId: '123',
    todoId: '456',
    title: 'Take out the trash',
    completed: false,
  },
  returnValues: 'ALL_OLD',
});

const putResult = await todoEntity.send(putCommand);
console.log(putResult.returnItem);

Conditional Puts

You can perform a put that only succeeds if a specified condition is met. To do this, use the ConditionalPut command and provide a condition in the command config.

const conditionalPut = new ConditionalPut({
  item: {
    userId: '123',
    todoId: '456',
    title: 'Take out the trash',
    completed: true,
  },
  condition: {
    completed: false,
  },
});

await todoEntity.send(conditionalPut);

In the above example, the put will only succeed if the existing item’s completed attribute is false.

Put Command Config

The Put command accepts the following input config:

{
  item: Schema;
  returnValues?: ReturnValue;
  returnItemCollectionMetrics?: ReturnItemCollectionMetrics;
  skipValidation?: boolean;
  timeoutMs?: number;
  abortController?: AbortController;
  returnConsumedCapacity?: ReturnConsumedCapacity;
}

Property	Type	Description
`item` (required)	`Schema`	The item to put into the table (`Schema` is the inferred type of your schema).
`returnValues?`	`ReturnValue`	Use this to request that the put operation return the item’s attributes as they appeared before the put operation, in case you are overwriting an existing item. Valid values are `ALL_OLD`, `ALL_NEW`, `UPDATED_OLD`, `UPDATED_NEW`, and `NONE`.
`returnItemCollectionMetrics?`	`ReturnItemCollectionMetrics`	Use this to request that the put operation return information about item collections, if any, that were affected by the operation. Valid values are `SIZE` and `NONE`.
`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`.

Put Command Result

The Put command returns the following result:

{
  returnItem?: Partial<Schema>;
  itemCollectionMetrics?: ItemCollectionMetrics;
  responseMetadata?: ResponseMetadata;
  consumedCapacity?: ConsumedCapacity;
}

Property	Type	Description
`returnItem?`	`Partial<Schema>`	The returned item as they appeared before the put operation, if requested via `returnValues` in the config.
`itemCollectionMetrics?`	`ItemCollectionMetrics`	Information about item collections, if any, that were affected by the operation.
`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.

Conditional Put Command Config

The ConditionalPut command accepts the following input config:

{
  item: Schema;
  condition: Condition;
  returnValues?: ReturnValue;
  returnValuesOnConditionCheckFailure?: ReturnValuesOnConditionCheckFailure;
  returnItemCollectionMetrics?: ReturnItemCollectionMetrics;
  skipValidation?: boolean;
  timeoutMs?: number;
  abortController?: AbortController;
  returnConsumedCapacity?: ReturnConsumedCapacity;
}

Property	Type	Description
`item` (required)	`Schema`	The item to put into the table (`Schema` is the inferred type of your schema).
`condition` (required)	`Condition`	A condition that must be satisfied in order for the put operation to succeed. See Conditions for more details.
`returnValues?`	`ReturnValue`	Use this to request that the put operation return the item’s attributes as they appeared before the put operation, in case you are overwriting an existing item. Valid values are `ALL_OLD`, `ALL_NEW`, `UPDATED_OLD`, `UPDATED_NEW`, and `NONE`.
`returnValuesOnConditionCheckFailure?`	`ReturnValuesOnConditionCheckFailure`	Use this to request that the put operation return the item’s attributes as they appeared before the failed condition check. Valid values are `ALL_OLD` and `NONE`.
`returnItemCollectionMetrics?`	`ReturnItemCollectionMetrics`	Use this to request that the put operation return information about item collections, if any, that were affected by the operation. Valid values are `SIZE` and `NONE`.
`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`.

Conditional Put Command Result

The ConditionalPut command returns the following result:

{
  returnItem?: Partial<Schema>;
  itemCollectionMetrics?: ItemCollectionMetrics;
  responseMetadata?: ResponseMetadata;
  consumedCapacity?: ConsumedCapacity;
}

Property	Type	Description
`returnItem?`	`Partial<Schema>`	The returned item as they appeared before the put operation, if requested via `returnValues` in the config.
`itemCollectionMetrics?`	`ItemCollectionMetrics`	Information about item collections, if any, that were affected by the operation.
`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 { Put } from 'dynamo-document-builder/commands/put';
import { ConditionalPut } from 'dynamo-document-builder/commands/conditional-put';