@@ -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 ):
0 commit comments