Delete

Use the Delete command to remove a single item from DynamoDB. This is the Document Builder command for a DeleteItem operation.

Basic Usage

Delete an item by 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 deleteCommand = new Delete({
  key: {
    userId: '123',
    todoId: '456',
  },
});

await todoEntity.send(deleteCommand);

Note

Currently, items in DynamoDB can only be deleted by primary key only, not by secondary indexes. If you need to delete an item using a secondary index, you must first perform a Get or Query operation to retrieve the primary key of the item, and then use that primary key to perform the Delete operation.

Returning the Deleted Item

You can request that the delete operation return the item’s attributes as they appeared before the delete operation. To do this, set the returnValues parameter in the command config.

const deleteCommand = new Delete({
  key: {
    userId: '123',
    todoId: '456',
  },
  returnValues: 'ALL_OLD',
});

const deleteResult = await todoEntity.send(deleteCommand);
console.log(deleteResult.deletedItem);

Deleted Item Type

The deletedItem type is always a Partial<T> of your schema type, since the deleted item may not exist or might only contain a subset of attributes.

Conditional Deletes

You can perform a delete that only succeeds if certain conditions are met. To do this, use the ConditionalDelete command and provide a condition in the command config.

const conditionalDelete = new ConditionalDelete({
  key: {
    userId: '123',
    todoId: '456',
  },
  condition: {
    completed: true,
  },
});

await todoEntity.send(conditionalDelete);

In the above example, the delete will only succeed if the completed attribute is true.

Defining Conditions

Document Builder provides a expressive API for defining conditions over DynamoDB’s base ConditionExpression, see Conditions for more details.

Delete Command Config

The Delete command accepts the following input config:

{
  key: Partial<Schema>;
  returnValues?: ReturnValue;
  returnItemCollectionMetrics?: ReturnItemCollectionMetrics;
  skipValidation?: boolean;
  timeoutMs?: number;
  abortController?: AbortController;
  returnConsumedCapacity?: ReturnConsumedCapacity;
}

Property	Type	Description
key (required)	Partial<Schema>	The primary key of the item to delete. 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).
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.

Delete Command Result

The Delete command returns the following result:

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

Property	Type	Description
deletedItem?	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 Delete Command Config

The ConditionalDelete command accepts the following input config:

{
  key: Partial<Schema>;
  returnValues?: ReturnValue;
  returnValuesOnConditionCheckFailure?: ReturnValuesOnConditionCheckFailure;
  returnItemCollectionMetrics?: ReturnItemCollectionMetrics;
  skipValidation?: boolean;
  timeoutMs?: number;
  abortController?: AbortController;
  returnConsumedCapacity?: ReturnConsumedCapacity;
}

Property	Type	Description
key (required)	Partial<Schema>	The primary key of the item to delete. 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).
condition (required)	Condition	A condition that must be satisfied in order for the delete 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 Delete Command Result

The ConditionalDelete command returns the following result:

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

Property	Type	Description
deletedItem?	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 { Delete } from 'dynamo-document-builder/commands/delete';
import { ConditionalDelete } from 'dynamo-document-builder/commands/conditional-delete';

API Reference

• Delete
• DeleteConfig
• DeleteResult
• ConditionalDelete
• ConditionalDeleteConfig
• ConditionalDeleteResult