XADD
XADD key [NOMKSTREAM] [<MAXLEN | MINID> [= | ~] threshold [LIMIT count]] <* | id> field value [field value ...]
- Available since:
- 5.0.0
- Time complexity:
- O(1) when adding a new entry, O(N) when trimming where N being the number of entries evicted.
- ACL categories:
-
@write,@stream,@fast,
将指定的流条目附加到指定键的流中。
如果键不存在，作为运行此命令的副作用，
键将以流值创建。可以通过NOMKSTREAM选项禁用流键的创建。
一个条目由一系列字段-值对组成。
字段-值对按照用户提供的顺序存储。
读取流的命令，如XRANGE或XREAD，保证返回的字段和值的顺序与XADD添加的顺序完全相同。
XADD 是 唯一的 Redis 命令，可以向流中添加数据，但
还有其他命令，例如 XDEL 和 XTRIM，能够
从流中删除数据。
将流ID指定为参数
流条目ID标识流中的给定条目。
如果指定的ID参数是*字符（星号ASCII字符），XADD命令将自动为您生成一个唯一的ID。然而，尽管在非常罕见的情况下才有用，也可以指定一个格式良好的ID，以便新条目将完全使用指定的ID添加。
ID由两个数字组成，中间用-字符分隔：
1526919030474-55
两个量都是64位数字。当ID自动生成时，第一部分是生成ID的Redis实例的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表）并且你真的希望Redis流的ID与这个其他系统的ID匹配时，才需要求助于特定的ID。
封顶流
XADD 包含了与 XTRIM 命令相同的语义 - 请参阅其文档页面以获取更多信息。
这允许通过一次调用 XADD 来添加新条目并控制流的大小，有效地将流限制在任意阈值内。
虽然精确修剪是可能的并且是默认的，但由于流的内部表示，使用 几乎精确 修剪（~ 参数）通过 XADD 添加条目并修剪流更为高效。
例如，以以下形式调用 XADD：
XADD mystream MAXLEN ~ 1000 * ... entry fields here ...
将添加一个新条目，但也会驱逐旧条目，以便流中仅包含1000个条目，或最多几十个条目。
关于流的附加信息
有关Redis流的更多信息，请查看我们的 Redis流介绍文档。
示例
RESP2 回复
以下之一：
- Bulk string reply: 添加条目的ID。如果星号（
*）作为id参数传递，则ID是自动生成的，否则命令仅返回用户在插入期间指定的相同ID。 - Nil reply: 如果给出了NOMKSTREAM选项且键不存在。
RESP3 回复
以下之一：
- Bulk string reply: 添加条目的ID。如果星号（
*）作为id参数传递，则ID是自动生成的，否则命令仅返回用户在插入期间指定的相同ID。 - Null reply: 如果给出了NOMKSTREAM选项且键不存在。
历史
- 从Redis版本6.2.0开始：添加了
NOMKSTREAM选项，MINID修剪策略和LIMIT选项。 - 从 Redis 7.0.0 版本开始：增加了对
-*