XADD

将指定的流条目附加到指定键的流中。如果该键不存在，则运行此命令的副作用是创建具有流值的键。可以通过 NOMKSTREAM 选项禁用流键的创建。

一个条目由一系列字段-值对组成。字段-值对以用户提供的相同顺序存储。读取流的命令（例如 XRANGE 或 XREAD）保证以 XADD 添加时的相同顺序返回字段和值。

XADD 是 *唯一* 可以向流中添加数据的 Valkey 命令，但也有其他命令（例如 XDEL 和 XTRIM）能够从流中删除数据。

将流 ID 指定为参数

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

如果指定的 ID 参数是 * 字符（星号 ASCII 字符），XADD 命令将为您自动生成一个唯一的 ID。然而，虽然在极少数情况下才有用，但可以指定一个格式良好的 ID，以便新条目将完全按照指定的 ID 添加。

ID 由两个以 - 字符分隔的数字指定

1526919030474-55

这两个值都是 64 位数字。当 ID 自动生成时，第一部分是生成 ID 的 Valkey 实例的 Unix 毫秒时间。第二部分只是一个序列号，用于区分在同一毫秒内生成的 ID。

您也可以指定一个不完整的 ID，它只包含毫秒部分，这被解释为序列部分的零值。要仅自动生成序列部分，请指定毫秒部分，后跟 - 分隔符和 * 字符

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

ID 保证始终是增量的：如果您比较刚插入条目的 ID，它将大于任何其他过去的 ID，因此流中的条目是完全有序的。为了保证这一特性，如果流中当前最高 ID 的时间大于实例的当前本地时间，将改用最高条目时间，并且 ID 的序列部分将递增。例如，当本地时钟跳回，或者在故障转移后新的主节点具有不同的绝对时间时，可能会发生这种情况。

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

有上限的流

XADD 包含了 XTRIM 命令的相同语义——有关更多信息，请参阅其文档页面。这允许通过一次调用 XADD 来添加新条目并控制流的大小，从而有效地将流限制在任意阈值内。尽管精确修剪是可能的并且是默认的，但由于流的内部表示，使用 **几乎精确** 修剪（~ 参数）通过 XADD 添加条目并修剪流效率更高。

例如，以以下形式调用 XADD

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

将添加一个新条目，但也会驱逐旧条目，以便流只包含 1000 个条目，或最多几十个更多。

关于流的附加信息

有关流的更多信息，请查阅我们的流简介文档。

示例

127.0.0.1:6379> XADD mystream * name Sara surname OConnor
"1714701491958-0"
127.0.0.1:6379> XADD mystream * field1 value1 field2 value2 field3 value3
"1714701491968-0"
127.0.0.1:6379> XLEN mystream
(integer) 2
127.0.0.1:6379> XRANGE mystream - +
1) 1) "1714701491958-0"
   2) 1) "name"
      2) "Sara"
      3) "surname"
      4) "OConnor"
2) 1) "1714701491968-0"
   2) 1) "field1"
      2) "value1"
      3) "field2"
      4) "value2"
      5) "field3"
      6) "value3"

RESP2 回复

以下之一

• Bulk string reply：添加条目的 ID。如果将星号（*）作为 *id* 参数传递，则 ID 是自动生成的；否则，命令只返回用户在插入时指定的相同 ID。

• Nil reply：如果提供了 NOMKSTREAM 选项且键不存在。

RESP3 回复

以下之一

• Bulk string reply：添加条目的 ID。如果将星号（*）作为 *id* 参数传递，则 ID 是自动生成的；否则，命令只返回用户在插入时指定的相同 ID。

• Null reply：如果提供了 NOMKSTREAM 选项且键不存在。

历史