TS.READ

读取指定时间戳之后的样本，可选择阻塞等待。

语法

TS.READ key timestamp [BLOCK milliseconds min count] [MAX COUNT max count]

引入版本：8.10.0

复杂度摘要：O(log(n)

在给定时间戳处或之后读取一批时间序列样本，返回最多 max_count 的最旧的合格样本（按递增时间戳排序）。默认情况下，TS.READ 会立即返回可用的内容；添加可选的 BLOCK 关键字以等待至少 min_count 样本存在或 milliseconds 过去（以先发生者为准）。

key可以是正则时间序列，也可以是压缩时间序列。

示例

必需参数

key

是时间序列的键名称。它可以识别常规系列或压缩系列。

timestamp

是读取的包含下界游标。该命令选择时间戳大于或等于已解析游标 (sample_timestamp >= resolved_timestamp) 的样本。

timestamp 是一个以毫秒为单位的非负整数 Unix 时间戳，或者是标记 -、+ 或 $ 之一：

价值	姓名	说明
非负整数	文字光标	以毫秒为单位的 Unix 时间戳。匹配是包容性的。 `0` 被接受并从头开始读取。
`-`	最早	系列中最早样本的时间戳，或者当系列为空或不存在时为 `0`。
`+`	最新	系列中最新样本的时间戳，或者当系列为空或不存在时为 `0`。光标是包容性的，因此最新的现有样本本身符合条件（与 `TS.RANGE` 对齐）。如果没有 `BLOCK`，调用会立即返回该样本；当 `BLOCK` 和 `min_count` 大于 `1` 时，它会阻塞，直到该时间戳或之后存在足够的样本为止。仅适用于第一次通话。
`$`	新	最新样本的时间戳加1，或者当系列为空或不存在时为`0`。只有服务器收到命令后报告的样本才符合资格；最新的现有样本被排除在外。

+ 和 $ 语义反映了 XREAD 和 XREADGROUP 的特殊 ID。当收到命令时，服务器会一次性解析所有哨兵，因此在客户端被阻止时光标保持稳定。将-、+、$原样发送到服务器；不要在客户端解决它们。

使用下表选择第一次调用的光标：

目标	首次调用`timestamp`
阅读完整的历史记录，然后阅读新的样本	`-` or `0`
从当前最新样本开始，含	`+`
只接收调用后添加的样品	`$`

对于每个后续调用，请使用 last_returned_timestamp + 1，这样您就不会收到任何遗漏和重复的消息。首次调用后请勿重复使用 + 或 $。如果没有返回样本，您可以使用相同的光标重试，具体取决于应用程序的交付策略。

可选参数

BLOCK milliseconds min_count

使命令阻塞而不是立即返回。当 BLOCK 存在时，该命令将等待，直到至少有 min_count 合格样本可用，直到 milliseconds 过去，或者直到键被移除（以先发生者为准）。

milliseconds 是非负整数超时。 0 的值意味着无限期地阻止，直到 min_count 样本变得可用或键被删除（与 BLPOP 和 XREAD BLOCK 0 的约定相同）。

min_count 是解锁阈值：命令在超时之前返回之前所需的合格样本数。它必须是一个正整数。当省略 BLOCK 时，该命令不会阻塞并立即返回可用的任何内容，即使没有样本合格也是如此。

MAX_COUNT max_count

是reply cap：返回的最大样本数。它必须是正整数，并且当使用 BLOCK 时，大于或等于 min_count。当未提供 MAX_COUNT 时，回复无限制。当存在比 max_count 多的匹配样本时，服务器首先返回最早的 max_count 样本，以便您可以向前翻页。

MAX_COUNT默认无限制；在使用大量历史记录时显式设置它以限制回复大小并启用分页。

BLOCK 和 MAX_COUNT 关键字是可选的、独立的，并且可以按任意顺序给出。省略BLOCK即可无阻塞读取；省略 MAX_COUNT 可使回复大小不受限制。没有值的关键字或任何杂散的尾随标记将被视为错误数量错误而被拒绝。

示例

Read history without blocking

创建时间序列并添加三个样本。

127.0.0.1:6379> TS.CREATE sensor:1
OK
127.0.0.1:6379> TS.ADD sensor:1 100 1.0
(integer) 100
127.0.0.1:6379> TS.ADD sensor:1 200 2.0
(integer) 200
127.0.0.1:6379> TS.ADD sensor:1 300 3.0
(integer) 300

无阻塞读取所有历史样本。如果没有 BLOCK 关键字，命令会立即返回，而 max_count 则不受限制。

127.0.0.1:6379> TS.READ sensor:1 0
1) 1) (integer) 100
   2) 1
2) 1) (integer) 200
   2) 2
3) 1) (integer) 300
   2) 3

- 哨兵相当于从最早的样本进行完整读取。

127.0.0.1:6379> TS.READ sensor:1 -

Page through history in bounded batches

每次调用最多读取两个样本，在每次后续调用时将光标前进到 last_returned_timestamp + 1。

127.0.0.1:6379> TS.READ sensor:1 - MAX_COUNT 2
1) 1) (integer) 100
   2) 1
2) 1) (integer) 200
   2) 2
127.0.0.1:6379> TS.READ sensor:1 201 MAX_COUNT 2
1) 1) (integer) 300
   2) 3

Start from the latest sample

从当前最新样本（含）开始。如果没有 BLOCK，则会立即返回。

127.0.0.1:6379> TS.READ sensor:1 +
1) 1) (integer) 300
   2) 3

对于 BLOCK 5000 2，相同的 + 调用会阻塞，直到时间戳大于或等于 300 的第二个样本到达，或者在 5000 毫秒后返回可用样本。

127.0.0.1:6379> TS.READ sensor:1 + BLOCK 5000 2

Tail only new samples

使用 $ 忽略已存在的所有内容并仅接收调用后添加的样本。 BLOCK 5000 1 等待第一个新样本长达 5000 毫秒。

127.0.0.1:6379> TS.READ sensor:1 $ BLOCK 5000 1

如果另一个客户端在 5000 毫秒内运行 TS.ADD sensor:1 400 4.0，则被阻止的调用将返回 [[400, 4]]。如果没有新样本到达，则返回一个空数组。

Partial flush on timeout

当无法到达 min_count 时，该命令将在超时后返回可用样本。这里BLOCK 1000 10无法达到10个样本，因此在1000毫秒后返回两个符合条件的样本。

127.0.0.1:6379> TS.READ sensor:1 101 BLOCK 1000 10
1) 1) (integer) 200
   2) 2
2) 1) (integer) 300
   2) 3

如果没有任何内容符合超时条件，则回复为空数组。

127.0.0.1:6379> TS.READ sensor:1 301 BLOCK 1000 1
(empty array)

Read from a compaction series

key可能是一个压缩系列。该命令可以返回压缩样本，并且使用 BLOCK 可以等待未来的压缩输出。

127.0.0.1:6379> TS.READ sensor:1:avg - BLOCK 10000 1

详细说明

何时使用`TS.READ`

应用程序通常根据时间序列数据（指标、传感器读数、金融价格和交易量或应用程序遥测）呈现图表，并且需要在新样本到达时保持这些图表最新。如果没有 TS.READ，应用程序通常会以固定间隔轮询 TS.RANGE 并检查自上次请求以来添加的样本，或者侦听键空间通知。这两种方法都有效，但它们需要定期轮询或额外的通知处理。

TS.READ 将其替换为单个可选的阻塞读取：应用程序发出一个调用并等待，直到新样本可用，然后附加它们并重复。这适合任何持续流式更新的内容——监控仪表板、实时图表、金融终端、物联网传感器源或警报系统——在没有添加新样本时无需发出重复的范围查询。

阻塞和检索语义

该命令从 key 读取时间戳大于或等于已解析游标的样本。
如果没有 BLOCK，该命令永远不会阻塞：它会立即返回最旧的合格样本中的 max_count，即使没有样本合格（空数组）。
对于 BLOCK milliseconds min_count，如果至少有 min_count 个匹配样本可用，服务器会立即返回最多 max_count 个最旧的合格样本。
当可用的 BLOCK 和少于 min_count 的匹配样本时，服务器会阻塞，直到达到 min_count、milliseconds 过去或键被删除。 BLOCK 0 无限期阻止。每个示例附加（TS.ADD、TS.MADD、TS.INCRBY、TS.DECRBY 和压缩规则写入目标键）都可以解锁被阻止的客户端。
超时时，服务器返回任何可用的内容，可以是空数组或少于 min_count 个样本。这是一个成功的回复，而不是一个错误。
如果在客户端被阻止（DEL、UNLINK、FLUSHDB、FLUSHALL、过期或驱逐）时键被删除，服务器将向被阻止的客户端返回一个空列表。这是一个成功的回复，而不是一个错误。
返回的样本按时间戳递增排序，包括样本乱序插入的情况。
等待同一键的多个阻塞客户端独立等待。接收样品的一个客户端不会为另一客户端消耗它们。

Redis Software 与 Redis Cloud 兼容性

Redis 软件	Redis Cloud	说明
❌ 不支持	❌ 灵活且每年 ❌免费和固定

返回值

RESP2

以下之一： * (整数回复, 简单字符串回复) 对中的数组回复表示（时间戳，值），按时间戳递增排序。当命令返回时没有可用的匹配样本时，或者在命令被阻止时移除键时，该数组为空。 * 简单错误回复在这些情况下：无效的时间戳、无效的 milliseconds、无效的 min_count 或 max_count、min_count 大于 max_count、参数数量错误、键类型错误、该命令与不允许阻塞的 BLOCK 一起使用（例如，在 MULTI 或 Lua 脚本内）等。

RESP3

以下之一： * (整数回复, 双重回复) 对中的数组回复表示（时间戳，值），按时间戳递增排序。当命令返回时没有可用的匹配样本时，或者在命令被阻止时移除键时，该数组为空。 * 简单错误回复在这些情况下：无效的时间戳、无效的 milliseconds、无效的 min_count 或 max_count、min_count 大于 max_count、参数数量错误、键类型错误、该命令与不允许阻塞的 BLOCK 一起使用（例如，在 MULTI 或 Lua 脚本内）等。

参见

TS.GET | TS.RANGE | TS.REVRANGE

Redis时间系列

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