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 one or more Query operations on a Table, and then runs BatchWriteCommands to batch delete the returned items. Automatically iterates through query pages if needed:

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)
  .entities(PokemonEntity)
  .query({ partition: 'ashKetchum' })
  .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)
  // Deletes only `Pokemons` and `Trainers`
  .entities(PokemonEntity, TrainerEntity)
  .query(query)
  .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)
  .entities(PokemonEntity, TrainerEntity)
  .query(query)
  .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 global 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 querying items that lack the entity internal attribute (e.g., when migrating to DynamoDB-Toolbox). In this case, DynamoDB-Toolbox attempts to format the item for each entity and disregards it if none succeed. Note that you can also use Middleware Stacks to reintroduce the entity attribute and improve performance.

Examples

Examples

Basic

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

Consistent

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

Index

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

Filtered

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

Multitenant

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

Aborted

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

await PokeTable.build(DeletePartitionCommand)
  .entities(PokemonEntity)
  .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: ... }