XDEL(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💅 XDEL — the valkey command manual, bestie edition ✨

okay so you found the xdel page, and honestly? iconic choice. this is the part of the valkey manual where we learn how to yeet entries out of a stream. let's get into it 🎀

✨ NAME ✨

xdel — returns the number of messages after removing them from a stream. that's it, that's the whole job description 💖

🌸 SYNOPSIS 🌸

XDEL key ID [ID...]

key first, then a whole lil list of IDs, one or more, no cap.

🦋 DESCRIPTION 🦋

so basically: xdel removes the specified entries from a stream, and hands you back the number of entries that actually got deleted. and here's the tea — that number may be less than the number of IDs you passed in, because some of those IDs might not even exist in the stream. gone girl behavior fr fr 🙈

normally you'd think of a Stream as an append-only data structure, like, once it's in there it's in there forever, right? well… Streams live in memory, bestie, so we absolutely can delete entries too. this is highkey useful, for example when you need to comply with certain privacy policies. main character data hygiene 💅

🧚 Understanding the low level details of entries deletion

okay this is the nerdy part and i love it here. streams are represented in a way that makes them super memory efficient: a radix tree is used to index macro-nodes that pack linearly tens of stream entries. so what actually happens when you delete an entry from a stream? the entry is not really evicted — it just gets marked as deleted. the way that it's lowkey still chilling there, just with a little "deleted" sticker on it 😭

eventually, if all the entries in a macro-node are marked as deleted, the whole node is destroyed and the memory reclaimed. so if you delete a large amount of entries from a stream — for instance more than 50% of the entries appended to the stream — the memory usage per entry may increment, because what happens is the stream will become fragmented. however! the stream performance will remain the same. no cap, the perf is fine 🫶

in future versions of Valkey it is possible that we'll trigger a node garbage collection in case a given macro-node reaches a given amount of deleted entries. currently, with the usage we anticipate for this data structure, it is not a good idea to add such complexity. so, like, noted for later 💜

💖 REPLY 💖

valkey-protocol(7) Integer reply: the number of entries that were deleted. a simple little integer, serving looks ✨

🔥 COMPLEXITY 🔥

O(1) for each single item to delete in the stream, regardless of the stream size. constant time per item even when your stream is a whole stadium of entries. slay 👑

🌈 ACL CATEGORIES 🌈

@fast @stream @write

⭐ HISTORY ⭐

  • Available since: 5.0.0

🍓 EXAMPLES 🍓

watch me add some stuff and then delete it, a full lil glow-up arc:

> XADD mystream * a 1
1538561698944-0
> XADD mystream * b 2
1538561700640-0
> XADD mystream * c 3
1538561701744-0
> XDEL mystream 1538561700640-0
(integer) 1
127.0.0.1:6379> XRANGE mystream - +
1) 1) 1538561698944-0
   2) 1) "a"
      2) "1"
2) 1) 1538561701744-0
   2) 1) "c"
      2) "3"

see how b just ✨ vanished ✨ and the integer said 1? that's the whole vibe. bye b, we hardly knew ye 💀

🎀 SEE ALSO 🎀

xack(3valkey), xadd(3valkey), xautoclaim(3valkey), xclaim(3valkey), xgroup(3valkey), xgroup-create(3valkey), xgroup-createconsumer(3valkey), xgroup-delconsumer(3valkey), xgroup-destroy(3valkey), xgroup-help(3valkey), xgroup-setid(3valkey), xinfo(3valkey), xinfo-consumers(3valkey), xinfo-groups(3valkey), xinfo-help(3valkey), xinfo-stream(3valkey), xlen(3valkey), xpending(3valkey), xrange(3valkey), xread(3valkey), xreadgroup(3valkey), xrevrange(3valkey), xsetid(3valkey), xtrim(3valkey) — the whole stream friend group, go say hi 💖

and that's a wrap on xdel, bestie! remember: deleted entries get marked, not instantly evicted, and you get back the count of what actually went poof. go forth and manage your streams, you absolute icon 🦋

Valkey 9.0.0, dated 2025-10-21 — this page came from the XDEL(3valkey) manual, and yeah, it's giving documentation but make it cute. mwah 💅✨

📦 where this page comes from