DELETE — remove items

View .md

Remove items — with the same two shapes as UPDATE. A WHERE naming the complete primary key is a native single-item delete; anything looser runs as a preview-first set-based delete whose first Run writes nothing. This page is about removing data; removing a table is DROP TABLE, a control-plane statement with a type-the-name confirmation — the two never collide.

Syntax

sql 
DELETE FROM "table"WHERE key predicates [AND conditions][RETURNING ALL OLD *]

RETURNING ALL OLD * echoes the item as it was before the delete — the last look you'll get. Read-only stages refuse deletes on every surface. Guide: Writes & transactions.

Use cases

Delete one item by its key Native

The precise removal — complete key, one native write, first press.

sql 
DELETE FROM "stage.Users"WHERE pk = 'USER#42' AND sk = 'PROFILE'
Executes asDeleteItem · Key: USER#42/PROFILE
Delete and keep a copy of what was removed Native

Audit trails and undo buffers — the deleted item comes back in the same round trip.

sql 
DELETE FROM "stage.Users"WHERE pk = 'USER#42' AND sk = 'PROFILE'RETURNING ALL OLD *
Executes asDeleteItem · ReturnValues: ALL_OLD
Sweep stale rows (preview-first) Scan — read the note

Clear outbox entries older than 30 days. No key in the WHERE → bulk delete: preview the matching rows first, then an unchanged second Run removes them, each write re-checking its predicate atomically.

sql 
DELETE FROM "stage.Outbox"WHERE CreatedAt < CURRENT_TIMESTAMP - 30
Executes asPreview first → one DeleteItem per row, each re-checking the WHERE as a ConditionExpression
  • Capped at 1,000 matched rows — past that it refuses and asks for a narrower WHERE.
  • The clock arithmetic folds before the wire: CURRENT_TIMESTAMP - 30 becomes a literal, disclosed in the strip.

Try it

Try it · DELETESample
Run it live in DynoStudio →
Executes asDeleteItem · stage.Users
DeleteItem Key: USER#42/PROFILE · ReturnValues: ALL_OLD
Complete key → one native delete; the old item echoes back once.
#pkNameRole
1USER#42Ada Okaforadmin
Fetched 1 item in 10ms · 0 RCU · 1 partition

Related: Writes & transactions · UPDATE · Transactions · Tables, indexes & replicas for DROP TABLE.

Was this page helpful?