Skip to content

feat(time-series): add TS.READ cursor read command#3322

Open
nkaradzhov wants to merge 2 commits into
redis:masterfrom
nkaradzhov:ts-read
Open

feat(time-series): add TS.READ cursor read command#3322
nkaradzhov wants to merge 2 commits into
redis:masterfrom
nkaradzhov:ts-read

Conversation

@nkaradzhov

@nkaradzhov nkaradzhov commented Jul 8, 2026

Copy link
Copy Markdown
Collaborator

This pull request adds client support for the RedisTimeSeries TS.READ command (since 8.10.0), a read-only, single-key cursor reader that returns a batch of (timestamp, value) samples with timestamp at or after a cursor, in ascending order. With the optional BLOCK group it waits until at least minCount qualifying samples exist or a timeout elapses, enabling continuous batch consumption of historical and newly appended samples without polling TS.RANGE.

Wire shape: TS.READ key timestamp [BLOCK milliseconds min_count] [MAX_COUNT max_count]. The timestamp cursor accepts a non-negative integer or one of the sentinels -/+/$ (exposed as TS_READ_TIMESTAMP). The BLOCK group is all-or-nothing; minCount may be omitted in the typed API (defaults to 1) but is always emitted on the wire. Replies reuse the existing TS.RANGE sample parser (RESP2/RESP3).

Behavior considerations:

  • Command is marked read-only and is not cacheable (server declares dont_cache); cluster clients route by the key's hash slot.
  • Blocking connection handling is the caller's responsibility, consistent with existing blocking commands (e.g. BLPOP); the command object carries no blocking flag. Callers opting into BLOCK should run it on an isolated connection.
  • An empty reply is a successful result (nothing qualifies, timeout, or key removal) — no automatic retry.

🤖 Generated with Claude Code


Note

Low Risk
Additive read-only command following existing TS command patterns; blocking behavior is opt-in and documented like other blocking Redis commands.

Overview
Adds client support for RedisTimeSeries TS.READ (Redis 8.10+): a read-only, single-key cursor read that returns ascending (timestamp, value) batches from an inclusive cursor, with optional BLOCK / MAX_COUNT.

The new command wires TS.READ key timestamp [BLOCK ms min_count] [MAX_COUNT n], exposes cursor sentinels as TS_READ_TIMESTAMP (-, +, $), defaults minCount to 1 when BLOCK is set, and parses replies via the existing range sample transformers. client.ts.read / READ are registered on the time-series module and TsReadTimestamp, TsReadOptions, and TS_READ_TIMESTAMP are exported from the package entry.

Tests cover argument encoding and integration behavior (including sentinels, MAX_COUNT, missing keys, and BLOCK sync/timeout cases) behind minimumDockerVersion: [8, 10].

Reviewed by Cursor Bugbot for commit dea3295. Bugbot is set up for automated code reviews on this repo. Configure here.

nkaradzhov and others added 2 commits July 8, 2026 17:26
Add client support for the RedisTimeSeries TS.READ command (since 8.10.0),
a read-only, single-key cursor reader that returns a batch of (timestamp,
value) samples with timestamp at or after a cursor, in ascending order.

Wire shape: TS.READ key timestamp [BLOCK milliseconds min_count]
[MAX_COUNT max_count]. The timestamp cursor accepts a non-negative integer
or one of the sentinels -, +, $ (exposed as TS_READ_TIMESTAMP). The BLOCK
group is all-or-nothing; minCount is optional in the typed API (defaults
to 1) but always emitted on the wire. Replies reuse the existing TS.RANGE
sample parser for RESP2 and RESP3.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- re-export TS_READ_TIMESTAMP/TsReadTimestamp/TsReadOptions from
  package entry; JSDoc {@link} target was unreachable for users
- narrow TsReadTimestamp to number | Date | sentinels: bare string
  in Timestamp absorbed the literals, any string compiled
- add integration tests for LATEST/NEW sentinels and BLOCK
  (synchronous path + timeout empty flush)
@nkaradzhov nkaradzhov marked this pull request as ready for review July 9, 2026 08:01
@nkaradzhov nkaradzhov requested a review from PavelPashov July 9, 2026 08:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant