添加消息

语法
XADD key [NOMKSTREAM] [<MAXLEN | MINID> [= | ~] threshold
  [LIMIT count]] <* | id> field value [field value ...]
可用时间
5.0.0
时间复杂度
添加新条目为 O(1)，修剪为 O(N)，其中 N 为被驱逐条目的数量。
ACL 类别
@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 流简介文档。

示例

XADD mystream * name Sara surname OConnor XADD mystream * field1 value1 field2 value2 field3 value3 XLEN mystream XRANGE mystream - +

RESP2 响应

以下之一

  • 批量字符串响应: 添加的条目的 ID。如果在插入时将星号 (*) 作为 id 参数传递，则 ID 是自动生成的，否则命令只返回用户在插入时指定的相同 ID。
  • 空响应: 如果给出 NOMKSTREAM 选项且键不存在。

RESP3 响应

以下之一

  • 批量字符串响应: 添加的条目的 ID。如果在插入时将星号 (*) 作为 id 参数传递，则 ID 是自动生成的，否则命令只返回用户在插入时指定的相同 ID。
  • 空响应: 如果给出 NOMKSTREAM 选项且键不存在。

历史

  • 从 Redis 6.2.0 版本开始：添加了 NOMKSTREAM 选项、MINID 修剪策略和 LIMIT 选项。
  • 从 Redis 7.0.0 版本开始：添加了对 <ms>-* 显式 ID 形式的支持。
RATE THIS PAGE
Back to top ↑