XADD

将新消息追加到流中。如果键不存在，则创建该键。

语法

XADD key [NOMKSTREAM] [KEEPREF | DELREF | ACKED] [IDMPAUTO producer-id | IDMP producer-id idempotent-id] [ [= | ~] threshold [LIMIT count]] field value [field value ...]

引入版本：5.0.0

复杂度摘要：O(1)

将指定的流条目附加到指定 key 处的流。如果该键不存在，XADD 将使用给定的流值创建一个新键，作为运行此命令的副作用。您可以使用 NOMKSTREAM 选项关闭键创建。

必需参数

key

流键的名称。

id

流条目ID。使用 * 自动生成唯一 ID，或以 <ms>-<seq> 格式指定格式正确的 ID（例如 1526919030474-55）。

field value [field value ...]

组成流条目的一个或多个字段值对。您必须提供至少一对字段值对。

可选参数

NOMKSTREAM

如果键不存在，则阻止创建新流。从 Redis 6.2.0 开始可用。

IDMPAUTO producer-id | IDMP producer-id idempotent-id

启用幂等消息处理（最多一次生产）以防止重复条目。从 Redis 8.6 开始可用。

IDMPAUTO producer-id：自动为指定的生产者-id生成唯一的幂等ID（iid）。 Redis 跟踪此 iid 以防止来自同一生产者 id 的重复消息。
IDMP producer-id idempotent-id：对给定的生产者 ID 使用指定的幂等 ID。如果已使用此生产者 ID/幂等 ID 组合，则该命令将返回原始条目的 ID，而不是创建副本。

Producer-id 标识消息源，而 idempot-id 确保该 Producer-id 的消息流中的唯一性。 Redis 维护最近的生产者 ID/幂等 ID 组合的内部映射，以检测和防止重复。

仅当条目 ID 为 *（自动生成）时才能指定两种模式。

使用 XCFGSET 配置幂等 ID 的保留时间 (IDMP-DURATION) 以及每个生产者跟踪的最大数量 (IDMP-MAXSIZE)。

请参阅幂等消息处理了解更多信息。

KEEPREF | DELREF | ACKED

Specifies how to handle consumer group references when trimming. If there are no consumer groups, these arguments have no effect.从 Redis 8.2 开始可用。

如果不指定选项，则默认使用KEEPREF。与需要这些选项之一的 XDELEX 和 XACKDEL 命令不同，这里它们是可选的以保持向后兼容性：

KEEPREF（默认）：修剪时，根据指定的策略（MAXLEN 或 MINID）从流中删除条目，无论它们是否被任何消费者组引用，但保留所有消费者组的 PEL（待处理条目列表）中对这些条目的现有引用。
DELREF：修剪时，根据指定的策略从流中删除条目，并从所有消费者组的 PEL 中删除对这些条目的所有引用。
ACKED：修剪时，仅删除所有消费者组读取并确认的条目。请注意，如果引用条目的数量大于 MAXLEN，修剪仍会在限制处停止。

MAXLEN | MINID [= | ~] threshold [LIMIT count]>

修剪流以维持特定大小或删除旧条目：

MAXLEN | MINID

修剪策略： - MAXLEN：只要流的长度超过指定阈值就驱逐条目 - MINID：驱逐 ID 低于指定阈值的条目（自 Redis 6.2.0 起可用）

= | ~

修剪运算符： - =：精确修剪（默认） - 修剪到精确阈值 - ~：近似修剪 - 更高效，可能会留下比阈值稍多的条目

threshold

修剪阈值： - 对于 MAXLEN：threshold 是一个非负整数，指定修剪后流中可以保留的最大条目数。 Redis 通过删除最旧的条目（即具有最低流 ID 的条目）来强制执行此操作，以便仅保留最新的条目。 - 对于 MINID：threshold 是流 ID。所有 ID 小于 threshold 的条目都会被修剪。所有 ID 大于或等于 threshold 的条目都会被保留。

LIMIT count

限制修剪期间要检查的条目数量。从 Redis 6.2.0 开始可用。如果未指定，Redis 使用默认值 100 * 宏节点中的条目数。指定 0 会完全禁用限制机制。

每个条目由字段值对列表组成。 Redis 按照您提供的顺序存储字段值对。读取流的命令（例如 XRANGE 或 XREAD）返回字段和值的顺序与使用 XADD 添加字段和值的顺序完全相同。

[!NOTE] XADD 是唯一可以将数据添加到流的 Redis 命令。但是，其他命令（例如 XDEL 和 XTRIM）可以从流中删除数据。

示例

> XADD mystream * name Sara surname OConnor
"4378417975-0"
> XADD mystream * field1 value1 field2 value2 field3 value3
"4378417976-0"
> XLEN mystream
(integer) 2
> XRANGE mystream - +
1) 1) "1774378417975-0"
   2) 1) "name"
      2) "Sara"
      3) "surname"
      4) "OConnor"
2) 1) "1774378417976-0"
   2) 1) "field1"
      2) "value1"
      3) "field2"
      4) "value2"
      5) "field3"
      6) "value3"

幂等消息处理示例

> XADD mystream IDMP producer1 msg1 * field value
"1774378417976-0"
> XADD mystream IDMP producer1 msg1 * field different_value
"1774378417976-0"
> XADD mystream IDMPAUTO producer2 * field value
"1774378417977-0"
> XADD mystream IDMPAUTO producer2 * field value
"1774378417977-0"
> XCFGSET mystream IDMP-DURATION 300 IDMP-MAXSIZE 1000
OK

详细说明

指定 Stream ID 作为参数

流条目ID标识流内的特定条目。

如果您指定 * 字符（星号）作为 ID 参数，XADD 会自动为您生成唯一的 ID。但是，您也可以指定格式正确的 ID 以添加具有该确切 ID 的新条目，但这仅在极少数情况下有用。

使用由 - 字符分隔的两个数字指定 ID：

1526919030474-55

两个数字都是 64 位整数。当Redis自动生成ID时，第一部分是生成ID的Redis实例的Unix时间（以毫秒为单位）。第二部分是序列号，用于区分同一毫秒内生成的ID。

您还可以指定仅包含毫秒部分的不完整 ID，Redis 将其解释为序列部分的零值。要仅自动生成序列部分，请指定毫秒部分，后跟 - 分隔符和 * 字符：

> XADD mystream 1526919030474-55 message "Hello,"
"1526919030474-55"
> XADD mystream 1526919030474-* message " World!"
"1526919030474-56"

Redis 保证 ID 始终是增量的：您插入的任何条目的 ID 将大于任何先前的 ID，因此条目在流内是完全排序的。为了保证此属性，如果流中当前顶部 ID 的时间大于实例的当前本地时间，Redis 将使用顶部条目时间来代替，并递增 ID 的序列部分。例如，当本地时钟向后跳时，或者在故障转移后新主设备具有不同的绝对时间时，可能会发生这种情况。

当您为 XADD 指定显式 ID 时，最小有效 ID 为 0-1，并且您为必须指定的 ID 大于当前流内的任何其他 ID，否则命令将失败并返回错误。仅当您有另一个系统生成唯一 ID（例如 SQL 表）并且您希望 Redis 流 ID 与其他系统中的 ID 相匹配时，指定显式 ID 通常才有用。

限制流

XADD 包含与 XTRIM 命令相同的语义 - 请参阅其文档页面以获取更多信息。这允许您添加新条目并通过对 XADD 的单次调用来检查流的大小，从而使用任意阈值有效地限制流。尽管精确修剪是可能的并且是默认设置，但由于流的内部表示，添加条目并使用 几乎准确 修剪（~ 参数）通过 XADD 修剪流会更有效。

例如调用XADD，形式如下：

XADD mystream MAXLEN ~ 1000 * ... entry fields here ...

这会添加一个新条目，但也会逐出旧条目，以便流仅包含 1000 个条目，或最多几十个条目。

有关流的附加信息

有关 Redis 流的更多信息，请参阅 Redis Streams文档介绍。

Redis Software 与 Redis Cloud 兼容性

Redis 软件	Redis Cloud	说明
✅ 标准 ✅ 主动-主动	✅ 标准 ✅ 主动-主动

返回值

RESP2

以下之一： * 批量字符串回复：添加条目的 ID。如果星号 (*) 作为 id 参数传递，则该 ID 是自动生成的，否则该命令仅返回用户在插入期间指定的相同 ID。当使用 IDMP 并检测到重复项时，返回原始条目的 ID。 * 无回复：如果给出 NOMKSTREAM 选项并且键不存在。

RESP3

以下之一： * 批量字符串回复：添加条目的 ID。如果星号 (*) 作为 id 参数传递，则该 ID 是自动生成的，否则该命令仅返回用户在插入期间指定的相同 ID。当使用 IDMP 并检测到重复项时，返回原始条目的 ID。 * 空回复：如果给出 NOMKSTREAM 选项并且键不存在。

资料来源：Redis 官方 XADD 文档；中文内容参考 Redis 文档许可。