DeletePartition

warning

DeletePartitionCommand is exposed as a quality of life improvement, but is NOT an official DynamoDB operation (eventhough we wish it was).

Use it with ⚠️ caution ⚠️! It can be long and costly on large partitions, and incomplete in case of inconsistent read.

Performs a paginated Query Operation on a Table and run subsequent BatchWriteCommands to batch delete returned items:

import { DeletePartitionCommand } from 'dynamodb-toolbox/table/actions/deletePartition'

const deletePartitionCommand = PokeTable.build(
  DeletePartitionCommand
)

await deletePartitionCommand.send()

Request

.query(...)

(required)

The partition to query, with optional index and range condition:

• partition: The partition key to query
• index (optional): The name of a secondary index to query
• range (optional): If the table or index has a sort key, an additional Range or Equality Condition

// Delete 'ashKetchum' pokemons
await PokeTable.build(DeletePartitionCommand)
  .query({ partition: 'ashKetchum' })
  .entities(PokemonEntity)
  .send()

info

See the QueryCommand documentation for more details.

.entities(...)

(required)

Provides a list of entities to filter the deleted items (via the internal entity attribute). Required to build underlying BatchDeleteRequests:

await PokeTable.build(DeletePartitionCommand)
  .query(query)
  // Deletes only `Pokemons` and `Trainers`
  .entities(PokemonEntity, TrainerEntity)
  .send()

.options(...)

Provides additional options:

await PokeTable.build(DeletePartitionCommand)
  .options({
    consistent: true,
    ...
  })
  .send()

You can use the DeletePartitionOptions type to explicitly type an object as a DeletePartitionCommand options object:

import type { DeletePartitionOptions } from 'dynamodb-toolbox/table/actions/deletePartition'

const queryOptions: DeletePartitionOptions<
  typeof PokeTable,
  [typeof PokemonEntity, typeof TrainerEntity]
  // 👇 Optional query
  { partition: string }
> = {
  consistent: true,
  ...
}

await PokeTable.build(DeletePartitionCommand)
  .query(query)
  .entities(PokemonEntity, TrainerEntity)
  .options(queryOptions)
  .send()

info

It is advised to provide entities and query first as they constrain the options type.

Available options (see the DynamoDB Query 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 a strongly consistent query (unavailable on secondary indexes).
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". (Applies for the query and the batch writes.)
tableName	string	-	Overrides the Table name. Mostly useful for multitenancy.
exclusiveStartKey	Key	-	The primary key of the first item that this operation evaluates.
filters	Record<string, Condition>	-	For each entity name, a condition that must be satisfied in order for evaluated items of this entity to be deleted (improves performances but does not reduce costs). See the ConditionParser action for more details on how to write conditions.
entityAttrFilter	boolean	true	By default, specifying entities introduces a Filter Expression on the entity internal attribute. Set this option to false to disable this behavior. This option is useful for deleting items that miss the entity internal attribute (e.g. when migrating to DynamoDB-Toolbox). You can use Middleware Stacks to introduce it manually.

Examples

Strongly consistent

await PokeTable.build(DeletePartitionCommand)
  .query({ partition: 'ashKetchum' })
  .entities(PokemonEntity)
  .options({ consistent: true })
  .send()

On index

await PokeTable.build(DeletePartitionCommand)
  .query({
    index: 'byTrainerId',
    partition: 'ashKetchum',
    range: { gte: 50 }
  })
  .entities(PokemonEntity)
  .send()

Filtered

await PokeTable.build(DeletePartitionCommand)
  .query({ partition: 'ashKetchum' })
  .entities(PokemonEntity, TrainerEntity)
  .options({
    filters: {
      POKEMONS: { attr: 'pokeType', eq: 'fire' },
      TRAINERS: { attr: 'age', gt: 18 }
    }
  })
  .send()

Multitenant

await PokeTable.build(DeletePartitionCommand)
  .query({ partition: 'ashKetchum' })
  .entities(PokemonEntity)
  .options({ tableName: `tenant-${tenantId}-pokemons` })
  .send()

Aborted

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

await PokeTable.build(DeletePartitionCommand)
  .query({ partition: 'ashKetchum' })
  .send({ abortSignal })

// 👇 Aborts the command
abortController.abort()

Response

The response syntax is similar to the DynamoDB Query API, except that:

• Items are not returned
• The query ConsumedCapacity is renamed as QueryConsumedCapacity
• The batch write ConsumedCapacity is renamed as BatchWriteConsumedCapacity

You can use the DeletePartitionResponse type to explicitly type an object as a DeletePartitionCommand response object:

import type { DeletePartitionResponse } from 'dynamodb-toolbox/table/actions/deletePartition'

const deletePartitionResponse: DeletePartitionResponse<
  typeof PokeTable,
  // 👇 Query
  { partition: 'ashKetchum' },
  // 👇 Optional entities
  [typeof PokemonEntity],
> = { Count: ... }