Skip to main content

DeleteItem Request Builder

Overview​

This section describes the EfficientDynamoDb API for building the DeleteItem request.

The IDeleteItemEntityRequestBuilder<TEntity> interface provides a builder pattern for constructing a DeleteItem operation in DynamoDB. It is designed to work with a database entity of type TEntity.

Use the DynamoDbContext.DeleteItem() method to get the builder:

var builder = ddbContext.DeleteItem();

For the DeleteItem request you only required to specify primary key using the WithPrimaryKey method. All other builder methods are optional and can be omitted. In this case, DynamoDB will use the default behavior.

DeleteItem Configuration​

WithPrimaryKey (with only Partition key)​

Specifies the partition key of the item to delete.

IDeleteItemEntityRequestBuilder<TEntity> WithPrimaryKey<TPk>(TPk pk);
info

It is required to specify the primary key for every DeleteItem request.

caution

Use this method if the table has only a partition key. If the table has both partition and sort keys, use WithPrimaryKey<TPk, TSk> instead.

Parameters​

  • pk: The partition key of the item.

Example​

builder = builder.WithPrimaryKey("partitionKey");

WithPrimaryKey (with both Partition and Sort keys)​

Specifies the partition and sort keys of the item to delete.

IDeleteItemEntityRequestBuilder<TEntity> WithPrimaryKey<TPk, TSk>(TPk pk, TSk sk);
info

It is required to specify the primary key for every DeleteItem request.

caution

Use this method only if the table has both partition and sort keys. If the table only has a partition key, use WithPrimaryKey<TPk> instead.

Parameters​

  • pk: The partition key of the item.
  • sk: The sort key of the item.

Example​

builder = builder.WithPrimaryKey("partitionKey", "sortKey");

WithCondition (Explicit condition)​

Specifies condition for the DeleteItem operation.

IDeleteItemEntityRequestBuilder<TEntity> WithCondition(FilterBase condition);

Parameters​

  • condition: The condition that is used to determine whether the DeleteItem operation should succeed or fail. Refer to our condition expression building guide to learn how to build a condition in EfficientDynamoDb.

Example​

var expr = Condition<EntityClass>.On(item => item.FirstName).EqualTo("John");
builder = builder.WithCondition(expr);

WithCondition (Function condition)​

Specifies the condition function for the DeleteItem operation.

IDeleteItemEntityRequestBuilder<TEntity> WithCondition(Func<EntityFilter<TEntity>, FilterBase> conditionSetup);

Parameters​

  • conditionSetup: The condition function that is used to determine whether the DeleteItem operation should succeed or fail. Refer to our condition expression building guide to learn how to build a condition in EfficientDynamoDb.

Example​

builder = builder.WithCondition(
    cond => cond.On(item => item.FirstName).EqualTo("John")
);

WithReturnValues​

Specifies the attributes to include in the response.

IDeleteItemEntityRequestBuilder<TEntity> WithReturnValues(ReturnValues returnValues);

If not specified, no values are returned in the response.

Parameters​

  • returnValues: ReturnValues enum option. Only ReturnValues.None and ReturnValues.AllOld are valid for DeleteItem operation. Passing ReturnValues.None is equivalent to not using the WithReturnValues method at all.

Example​

builder = builder.WithReturnValues(ReturnValues.AllOld);

WithReturnValuesOnConditionCheckFailure​

Specifies how to handle return values if the operation fails.

IDeleteItemEntityRequestBuilder<TEntity> WithReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure option)

If not specified, no values are returned in case of condition check failure.

Parameters​

  • option: Option for handling return values on condition check failure.

Example​

builder = builder.WithReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.AllOld);

WithReturnConsumedCapacity​

Specifies the consumed capacity details to include in the response.

IDeleteItemEntityRequestBuilder<TEntity> WithReturnConsumedCapacity(ReturnConsumedCapacity returnConsumedCapacity);

If not specified, no consumed capacity info is returned in the response.

Parameters​

  • returnConsumedCapacity: The type of consumed capacity information to return. Setting it to ReturnConsumedCapacity.None is equivalent to not using the ReturnConsumedCapacity() method at all.

Example​

builder = builder.WithReturnConsumedCapacity(ReturnConsumedCapacity.Total);

AsDocument​

Represents the returned item as a Document.

This method changes the type of the builder.

IDeleteItemDocumentRequestBuilder<TEntity> AsDocument();

Example​

var documentBuilder = builder.AsDocument();

After execution, this DeleteItem request will return the Document instead of the original entity of the builder.

SuppressThrowing​

Prevents the DeleteItem operation from throwing an exception in case of any failure. Instead, the execution methods will return an OpResult or OpResult<T> that encapsulates either a successful result or an error.

This method returns a different type of the builder to indicate that exception suppression is active.

ISuppressedDeleteItemEntityRequestBuilder<TEntity> SuppressThrowing();

Example​

var result = await builder.SuppressThrowing().ExecuteAsync();
if (result.IsSuccess)
{
    // Handle successful execution.
}
else
{
    var exception = result.Exception;
    // Handle error.
}

DeleteItem Execution​

There are 2 versions of every query execution method: regular and document. All versions have same parameters, the only difference is entity type returned value:

  • In most cases, the original entity TEntity is returned.
  • If AsDocuments() was used, the execution method will contain the entity type of Document.
  • If SuppressThrowing() was used, the execution method will return an OpResult<T> where T is one of the types above.

For simplicity, this document covers only regular version of execution methods.

ExecuteAsync​

Executes the DeleteItem operation.

Task ExecuteAsync(CancellationToken cancellationToken = default);

Parameters​

  • cancellationToken: Token that can be used to cancel the task.

Example​

await builder.ExecuteAsync();

ToItemAsync​

Executes the DeleteItem operation and returns the item before the deletion.

The item is returned as it appeared before the DeleteItem operation, but only if WithReturnValues with ReturnValues.AllOld was specified in the request chain. Otherwise, null is returned.

Task<TEntity?> ToItemAsync(CancellationToken cancellationToken = default);

Parameters​

  • cancellationToken: Token that can be used to cancel the task.

Example​

var item = await builder.ToItemAsync();

ToResponseAsync​

Executes the DeleteItem operation and returns the deserialized response. Besides the item, this response contains ConsumedCapacity property if WithReturnConsumedCapacity was used.

Task<DeleteItemEntityResponse<TEntity>> ToResponseAsync(CancellationToken cancellationToken = default);

Example​

var response = await builder.ToResponseAsync();
var item = response.Item;
var consumedCapacity = response.ConsumedCapacity;