XADD

语法

XADD key [NOMKSTREAM] [<MAXLEN | MINID> [= | ~] threshold
  [LIMIT count]] <* | id> field value [field value ...]

可用版本: Redis Open Source 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 ...

Will add a new entry but will also evict old entries so that the stream will contain only 1000 entries, or at most a few tens more.

有关流的更多信息

有关 Redis 流的更多信息，请查看我们的Redis 流介绍文档。

示例

RESP2 回复

以下之一

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

RESP3 回复