XDELEX

Syntax
XDELEX key [KEEPREF | DELREF | ACKED] IDS numids id [id ...]
Available since:
Redis Open Source 8.2.0
Time complexity:
O(1) for each single item to delete in the stream, regardless of the stream size.
ACL categories:
@write, @stream, @fast,

Deletes one or multiple entries from the stream at the specified key.

XDELEX is an extension of the Redis Streams XDEL command that provides more control over how message entries are deleted concerning consumer groups.

Required arguments

key

The name of the stream key.

IDS numids id [id ...]

The IDS block specifying which entries to delete:

  • numids: The number of IDs that follow
  • id [id ...]: One or more stream entry IDs to delete

Note: The IDS block can be at any position in the command, same as other commands.

Optional arguments

KEEPREF | DELREF | ACKED

Specifies how to handle consumer group references when deleting entries. Available since Redis 8.2. If no option is specified, KEEPREF is used by default:

  • KEEPREF (default): Deletes the specified entries from the stream, but preserves existing references to these entries in all consumer groups' PEL (Pending Entries List). This behavior is similar to XDEL.
  • DELREF: Deletes the specified entries from the stream and also removes all references to these entries from all consumer groups' pending entry lists, effectively cleaning up all traces of the messages. If an entry ID is not in the stream, but there are dangling references, XDELEX with DELREF would still remove all those references.
  • ACKED: Only deletes entries that were read and acknowledged by all consumer groups.

The command provides fine-grained control over stream entry deletion, particularly useful when working with consumer groups where you need to manage pending entry references carefully.

Examples

Return information

One of the following:

  • Array reply: -1 for each requested ID when the given key does not exist.
  • Array reply: For each ID:
    • Integer reply: -1 if no such ID exists in the provided stream key.
    • Integer reply: 1 if the entry was deleted from the stream.
    • Integer reply: 2 if the entry was not deleted, but there are still dangling references (ACKED option).