Skip to content

Commit 059d1e9

Browse files
committed
Fixed TS.NRANGE commands to correctly apply aggregators (#4225)
* Fixed TS.NRANGE commands to correctly apply aggregators * Added testing fixed docs
1 parent d486a0a commit 059d1e9

4 files changed

Lines changed: 162 additions & 78 deletions

File tree

‎redis/commands/timeseries/commands.py‎

Lines changed: 56 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1174,11 +1174,17 @@ def nrange(
11741174
Query an explicit list of time-series over a range in forward direction
11751175
and return timestamp-major rows ordered by increasing timestamp.
11761176
1177-
Each returned row is ``[timestamp, [value_for_key_0, value_for_key_1,
1178-
...]]`` where the value array preserves the input ``keys`` order. A key
1179-
with no sample (or no aggregation bucket) at a row's timestamp is
1180-
reported as ``NaN``, which is indistinguishable from a stored or
1181-
aggregated ``NaN``.
1177+
Each returned row is ``[timestamp, [value, ...]]``. With no aggregation
1178+
-- or a single-aggregator spec per key -- the value array holds exactly
1179+
one value per queried key, in the input ``keys`` order. When a per-key
1180+
AGGREGATION spec lists several aggregators (e.g. ``"avg,max"``), that key
1181+
contributes one value per aggregator in the order the aggregators were
1182+
listed, and the row's value array is those per-key blocks concatenated in
1183+
``keys`` order. For example ``keys=[a, b]`` with
1184+
``aggregators=["avg,max", "sum"]`` yields ``[a_avg, a_max, b_sum]`` for
1185+
every row. A key (or aggregator column) with no sample or aggregation
1186+
bucket at a row's timestamp is reported as ``NaN``, which is
1187+
indistinguishable from a stored or aggregated ``NaN``.
11821188
11831189
All keys must hash to the same slot when used against a cluster; this
11841190
command is routed as a single-shard, key command and is never split
@@ -1201,13 +1207,15 @@ def nrange(
12011207
Limits the number of returned rows, applied after the
12021208
merge in increasing-timestamp order.
12031209
aggregators:
1204-
Optional aggregation. Requires exactly one aggregator per key,
1205-
emitted as separate tokens. A single aggregator string is
1206-
expanded to one token per key as a convenience; passing a list
1207-
whose length differs from ``keys`` raises ``DataError``. Valid
1208-
values: [`avg`, `sum`, `min`, `max`, `range`, `count`, `first`,
1209-
`last`, `std.p`, `std.s`, `var.p`, `var.s`, `twa`, `countNaN`,
1210-
`countAll`].
1210+
Optional aggregation, with exactly one spec token per key (a
1211+
single aggregator is never broadcast across keys). Each per-key
1212+
spec is a string and may list several comma-separated
1213+
aggregators, e.g. ``["avg,max", "sum"]`` builds
1214+
``AGGREGATION avg,max sum`` for two keys. A bare string is the
1215+
spec for a single-key query; a number of specs that differs from
1216+
``keys`` raises ``DataError``. Valid aggregators: [`avg`, `sum`,
1217+
`min`, `max`, `range`, `count`, `first`, `last`, `std.p`,
1218+
`std.s`, `var.p`, `var.s`, `twa`, `countNaN`, `countAll`].
12111219
bucket_size_msec:
12121220
Time bucket for aggregation in milliseconds. Shared by all keys.
12131221
filter_by_ts:
@@ -1302,11 +1310,17 @@ def nrevrange(
13021310
Query an explicit list of time-series over a range in reverse direction
13031311
and return timestamp-major rows ordered by decreasing timestamp.
13041312
1305-
Each returned row is ``[timestamp, [value_for_key_0, value_for_key_1,
1306-
...]]`` where the value array preserves the input ``keys`` order. A key
1307-
with no sample (or no aggregation bucket) at a row's timestamp is
1308-
reported as ``NaN``, which is indistinguishable from a stored or
1309-
aggregated ``NaN``.
1313+
Each returned row is ``[timestamp, [value, ...]]``. With no aggregation
1314+
-- or a single-aggregator spec per key -- the value array holds exactly
1315+
one value per queried key, in the input ``keys`` order. When a per-key
1316+
AGGREGATION spec lists several aggregators (e.g. ``"avg,max"``), that key
1317+
contributes one value per aggregator in the order the aggregators were
1318+
listed, and the row's value array is those per-key blocks concatenated in
1319+
``keys`` order. For example ``keys=[a, b]`` with
1320+
``aggregators=["avg,max", "sum"]`` yields ``[a_avg, a_max, b_sum]`` for
1321+
every row. A key (or aggregator column) with no sample or aggregation
1322+
bucket at a row's timestamp is reported as ``NaN``, which is
1323+
indistinguishable from a stored or aggregated ``NaN``.
13101324
13111325
All keys must hash to the same slot when used against a cluster; this
13121326
command is routed as a single-shard, key command and is never split
@@ -1329,13 +1343,15 @@ def nrevrange(
13291343
Limits the number of returned rows, applied after the
13301344
merge in decreasing-timestamp order.
13311345
aggregators:
1332-
Optional aggregation. Requires exactly one aggregator per key,
1333-
emitted as separate tokens. A single aggregator string is
1334-
expanded to one token per key as a convenience; passing a list
1335-
whose length differs from ``keys`` raises ``DataError``. Valid
1336-
values: [`avg`, `sum`, `min`, `max`, `range`, `count`, `first`,
1337-
`last`, `std.p`, `std.s`, `var.p`, `var.s`, `twa`, `countNaN`,
1338-
`countAll`].
1346+
Optional aggregation, with exactly one spec token per key (a
1347+
single aggregator is never broadcast across keys). Each per-key
1348+
spec is a string and may list several comma-separated
1349+
aggregators, e.g. ``["avg,max", "sum"]`` builds
1350+
``AGGREGATION avg,max sum`` for two keys. A bare string is the
1351+
spec for a single-key query; a number of specs that differs from
1352+
``keys`` raises ``DataError``. Valid aggregators: [`avg`, `sum`,
1353+
`min`, `max`, `range`, `count`, `first`, `last`, `std.p`,
1354+
`std.s`, `var.p`, `var.s`, `twa`, `countNaN`, `countAll`].
13391355
bucket_size_msec:
13401356
Time bucket for aggregation in milliseconds. Shared by all keys.
13411357
filter_by_ts:
@@ -2028,25 +2044,27 @@ def _append_n_aggregation(
20282044
bucket_size_msec: int | None,
20292045
numkeys: int,
20302046
):
2031-
"""Append AGGREGATION property for TS.NRANGE / TS.NREVRANGE.
2032-
2033-
Unlike TS.RANGE, these commands require exactly one aggregator per
2034-
queried key, emitted as separate tokens (never a single comma-joined
2035-
token and never a single aggregator broadcast across keys). A single
2036-
aggregator string is expanded to one token per key as a convenience.
2047+
"""Append the AGGREGATION clause for TS.NRANGE / TS.NREVRANGE.
2048+
2049+
These commands take exactly one aggregation spec token per queried key;
2050+
a single aggregator is never broadcast across keys. A spec token may hold
2051+
several comma-separated aggregators, so the wire form is e.g.
2052+
``AGGREGATION avg,max sum 1000`` for two keys -- key 0 aggregated by both
2053+
``avg`` and ``max``, key 1 by ``sum``. Pass one spec string per key, each
2054+
optionally comma-joined (``["avg,max", "sum"]``); a bare string is the
2055+
spec for a single-key query. (Matches RedisTimeSeries PR #2079, which
2056+
replaced the earlier single comma-joined / broadcast token.)
20372057
"""
20382058
if aggregators is None:
20392059
return
2040-
if isinstance(aggregators, str):
2041-
aggregators = [aggregators] * numkeys
2042-
else:
2043-
aggregators = list(aggregators)
2044-
if len(aggregators) != numkeys:
2060+
specs = [aggregators] if isinstance(aggregators, str) else list(aggregators)
2061+
if len(specs) != numkeys:
20452062
raise DataError(
2046-
"AGGREGATION requires exactly one aggregator per key "
2047-
f"(expected {numkeys}, got {len(aggregators)})."
2063+
"AGGREGATION requires exactly one aggregation spec per key "
2064+
f"(expected {numkeys}, got {len(specs)}); a spec may list "
2065+
"multiple comma-separated aggregators."
20482066
)
2049-
params.extend(["AGGREGATION", *aggregators, bucket_size_msec])
2067+
params.extend(["AGGREGATION", *specs, bucket_size_msec])
20502068

20512069
@staticmethod
20522070
def _append_chunk_size(params: list[EncodableT], chunk_size: int | None):

‎redis/commands/timeseries/utils.py‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -64,10 +64,13 @@ def parse_n_range(response, **kwargs):
6464
"""Parse the TS.NRANGE / TS.NREVRANGE response.
6565
6666
The wire shape is ``[[timestamp, [value_0, value_1, ...]], ...]`` where the
67-
value array preserves input key order and ``values`` length equals the
68-
number of queried keys. Rows are returned in server order (never re-sorted
69-
or reversed), and a missing raw sample or missing aggregation bucket is kept
70-
as ``float('nan')`` rather than converted to ``None``.
67+
value array preserves input key order. Its length equals the number of
68+
queried keys, except when a per-key AGGREGATION spec lists multiple
69+
aggregators: each such key then contributes one value per aggregator (in
70+
spec order), concatenated in key order. Rows are returned in server order
71+
(never re-sorted or reversed), and a missing raw sample or missing
72+
aggregation bucket is kept as ``float('nan')`` rather than converted to
73+
``None``.
7174
"""
7275
if not response:
7376
return []

‎tests/test_asyncio/test_timeseries.py‎

Lines changed: 39 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1768,6 +1768,31 @@ async def test_nrange_aggregation_one_per_key(decoded_r: redis.Redis):
17681768
_assert_nrange_rows(res, [[0, [2.0, 5.0]], [10, [4.0, 7.0]]])
17691769

17701770

1771+
@pytest.mark.redismod
1772+
@skip_if_server_version_lt("8.9.0")
1773+
async def test_nrange_multiple_aggregators_per_key_layout(decoded_r: redis.Redis):
1774+
# A per-key spec may list several aggregators. That key then contributes one
1775+
# value per aggregator (in spec order), and each row's value array is the
1776+
# per-key blocks concatenated in key order: here [a_avg, a_max, b_sum].
1777+
# key a: bucket [0,10) avg=2 max=3; bucket [10,20) avg=15 max=20
1778+
for ts, val in [(0, 1.0), (5, 3.0), (10, 10.0), (15, 20.0)]:
1779+
await decoded_r.ts().add("{s}:a", ts, val)
1780+
# key b: bucket [0,10) sum=10; bucket [10,20) sum=7
1781+
for ts, val in [(0, 5.0), (5, 5.0), (10, 7.0)]:
1782+
await decoded_r.ts().add("{s}:b", ts, val)
1783+
1784+
res = await decoded_r.ts().nrange(
1785+
["{s}:a", "{s}:b"],
1786+
from_time=0,
1787+
to_time=20,
1788+
aggregators=["avg,max", "sum"],
1789+
bucket_size_msec=10,
1790+
)
1791+
_assert_nrange_rows(res, [[0, [2.0, 3.0, 10.0]], [10, [15.0, 20.0, 7.0]]])
1792+
# 2 columns for key a (avg, max) + 1 for key b (sum).
1793+
assert all(len(row[1]) == 3 for row in res)
1794+
1795+
17711796
@pytest.mark.redismod
17721797
@skip_if_server_version_lt("8.9.0")
17731798
async def test_nrange_count_limits_rows(decoded_r: redis.Redis):
@@ -1786,29 +1811,25 @@ async def test_nrange_empty_result(decoded_r: redis.Redis):
17861811

17871812
@pytest.mark.redismod
17881813
@skip_if_server_version_lt("8.9.0")
1789-
async def test_nrange_single_aggregator_applies_to_all_keys(decoded_r: redis.Redis):
1790-
for ts, val in [(0, 1.0), (1, 2.0), (10, 3.0), (11, 4.0)]:
1791-
await decoded_r.ts().add("{s}:a", ts, val)
1792-
for ts, val in [(0, 5.0), (1, 6.0), (10, 7.0), (11, 8.0)]:
1793-
await decoded_r.ts().add("{s}:b", ts, val)
1794-
1795-
# A single aggregator string is expanded to one token per key; here
1796-
# "max" is applied to both series.
1797-
res = await decoded_r.ts().nrange(
1798-
["{s}:a", "{s}:b"],
1799-
from_time=0,
1800-
to_time=20,
1801-
aggregators="max",
1802-
bucket_size_msec=10,
1803-
)
1804-
_assert_nrange_rows(res, [[0, [2.0, 6.0]], [10, [4.0, 8.0]]])
1814+
async def test_nrange_single_aggregator_multi_key_raises(decoded_r: redis.Redis):
1815+
# A single aggregator is NOT broadcast across keys (RedisTimeSeries PR
1816+
# #2079): with more than one key, each needs its own spec token. Raised
1817+
# client-side before any server round trip.
1818+
with pytest.raises(redis.DataError, match="one aggregation spec per key"):
1819+
await decoded_r.ts().nrange(
1820+
["{s}:a", "{s}:b"],
1821+
from_time=0,
1822+
to_time=20,
1823+
aggregators="max",
1824+
bucket_size_msec=10,
1825+
)
18051826

18061827

18071828
@pytest.mark.redismod
18081829
@skip_if_server_version_lt("8.9.0")
18091830
async def test_nrange_aggregator_count_mismatch_raises(decoded_r: redis.Redis):
1810-
# An aggregator list whose length differs from the key count is invalid.
1811-
with pytest.raises(redis.DataError, match="one aggregator per key"):
1831+
# A spec list whose length differs from the key count is invalid.
1832+
with pytest.raises(redis.DataError, match="one aggregation spec per key"):
18121833
await decoded_r.ts().nrange(
18131834
["{s}:a", "{s}:b"],
18141835
from_time=0,

‎tests/test_timeseries.py‎

Lines changed: 60 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
import pytest
66
import redis
7+
from redis.commands.timeseries.commands import TimeSeriesCommands
78

89
from .conftest import (
910
_get_client,
@@ -2017,6 +2018,31 @@ def test_nrange_aggregation_one_per_key(client):
20172018
_assert_nrange_rows(res, [[0, [2.0, 5.0]], [10, [4.0, 7.0]]])
20182019

20192020

2021+
@pytest.mark.redismod
2022+
@skip_if_server_version_lt("8.9.0")
2023+
def test_nrange_multiple_aggregators_per_key_layout(client):
2024+
# A per-key spec may list several aggregators. That key then contributes one
2025+
# value per aggregator (in spec order), and each row's value array is the
2026+
# per-key blocks concatenated in key order: here [a_avg, a_max, b_sum].
2027+
# key a: bucket [0,10) avg=2 max=3; bucket [10,20) avg=15 max=20
2028+
for ts, val in [(0, 1.0), (5, 3.0), (10, 10.0), (15, 20.0)]:
2029+
client.ts().add("{s}:a", ts, val)
2030+
# key b: bucket [0,10) sum=10; bucket [10,20) sum=7
2031+
for ts, val in [(0, 5.0), (5, 5.0), (10, 7.0)]:
2032+
client.ts().add("{s}:b", ts, val)
2033+
2034+
res = client.ts().nrange(
2035+
["{s}:a", "{s}:b"],
2036+
from_time=0,
2037+
to_time=20,
2038+
aggregators=["avg,max", "sum"],
2039+
bucket_size_msec=10,
2040+
)
2041+
_assert_nrange_rows(res, [[0, [2.0, 3.0, 10.0]], [10, [15.0, 20.0, 7.0]]])
2042+
# 2 columns for key a (avg, max) + 1 for key b (sum).
2043+
assert all(len(row[1]) == 3 for row in res)
2044+
2045+
20202046
@pytest.mark.redismod
20212047
@skip_if_server_version_lt("8.9.0")
20222048
def test_nrange_count_limits_rows(client):
@@ -2034,29 +2060,29 @@ def test_nrange_empty_result(client):
20342060

20352061
@pytest.mark.redismod
20362062
@skip_if_server_version_lt("8.9.0")
2037-
def test_nrange_single_aggregator_applies_to_all_keys(client):
2038-
for ts, val in [(0, 1.0), (1, 2.0), (10, 3.0), (11, 4.0)]:
2039-
client.ts().add("{s}:a", ts, val)
2040-
for ts, val in [(0, 5.0), (1, 6.0), (10, 7.0), (11, 8.0)]:
2041-
client.ts().add("{s}:b", ts, val)
2042-
2043-
# A single aggregator string is expanded to one token per key; here
2044-
# "max" is applied to both series.
2045-
res = client.ts().nrange(
2046-
["{s}:a", "{s}:b"],
2047-
from_time=0,
2048-
to_time=20,
2049-
aggregators="max",
2050-
bucket_size_msec=10,
2051-
)
2052-
_assert_nrange_rows(res, [[0, [2.0, 6.0]], [10, [4.0, 8.0]]])
2063+
def test_nrange_single_aggregator_multi_key_raises(client):
2064+
# A single aggregator is NOT broadcast across keys (RedisTimeSeries PR
2065+
# #2079): with more than one key, each needs its own spec token. Raised
2066+
# client-side before any server round trip.
2067+
with pytest.raises(
2068+
redis.exceptions.DataError, match="one aggregation spec per key"
2069+
):
2070+
client.ts().nrange(
2071+
["{s}:a", "{s}:b"],
2072+
from_time=0,
2073+
to_time=20,
2074+
aggregators="max",
2075+
bucket_size_msec=10,
2076+
)
20532077

20542078

20552079
@pytest.mark.redismod
20562080
@skip_if_server_version_lt("8.9.0")
20572081
def test_nrange_aggregator_count_mismatch_raises(client):
2058-
# An aggregator list whose length differs from the key count is invalid.
2059-
with pytest.raises(redis.exceptions.DataError, match="one aggregator per key"):
2082+
# A spec list whose length differs from the key count is invalid.
2083+
with pytest.raises(
2084+
redis.exceptions.DataError, match="one aggregation spec per key"
2085+
):
20602086
client.ts().nrange(
20612087
["{s}:a", "{s}:b"],
20622088
from_time=0,
@@ -2066,6 +2092,22 @@ def test_nrange_aggregator_count_mismatch_raises(client):
20662092
)
20672093

20682094

2095+
def test_nrange_aggregation_builds_one_spec_token_per_key():
2096+
# Server-free: each per-key spec is its own token and may hold multiple
2097+
# comma-separated aggregators -> AGGREGATION avg,max sum 1000 for two keys
2098+
# (RedisTimeSeries PR #2079; no broadcast, no single comma-joined token).
2099+
params = []
2100+
TimeSeriesCommands._append_n_aggregation(params, ["avg,max", "sum"], 1000, 2)
2101+
assert params == ["AGGREGATION", "avg,max", "sum", 1000]
2102+
2103+
2104+
def test_nrange_aggregation_single_key_single_spec():
2105+
# Server-free: a bare string is the single-key spec (may be comma-joined).
2106+
params = []
2107+
TimeSeriesCommands._append_n_aggregation(params, "avg,max", 1000, 1)
2108+
assert params == ["AGGREGATION", "avg,max", 1000]
2109+
2110+
20692111
@pytest.mark.redismod
20702112
@skip_if_server_version_lt("8.9.0")
20712113
def test_nrange_empty_keys_raises(client):

0 commit comments

Comments
 (0)