Debian Codegraph @

valkey/commands/timeseries/commands.py

raw
1 from typing import Dict, List, Optional, Tuple, Union
2
3 from valkey.exceptions import DataError
4 from valkey.typing import KeyT, Number
5
6 ADD_CMD = "TS.ADD"
7 ALTER_CMD = "TS.ALTER"
8 CREATERULE_CMD = "TS.CREATERULE"
9 CREATE_CMD = "TS.CREATE"
10 DECRBY_CMD = "TS.DECRBY"
11 DELETERULE_CMD = "TS.DELETERULE"
12 DEL_CMD = "TS.DEL"
13 GET_CMD = "TS.GET"
14 INCRBY_CMD = "TS.INCRBY"
15 INFO_CMD = "TS.INFO"
16 MADD_CMD = "TS.MADD"
17 MGET_CMD = "TS.MGET"
18 MRANGE_CMD = "TS.MRANGE"
19 MREVRANGE_CMD = "TS.MREVRANGE"
20 QUERYINDEX_CMD = "TS.QUERYINDEX"
21 RANGE_CMD = "TS.RANGE"
22 REVRANGE_CMD = "TS.REVRANGE"
23
24
25 class TimeSeriesCommands:
26 """RedisTimeSeries Commands."""
27
28 def create(
29 self,
30 key: KeyT,
31 retention_msecs: Optional[int] = None,
32 uncompressed: Optional[bool] = False,
33 labels: Optional[Dict[str, str]] = None,
34 chunk_size: Optional[int] = None,
35 duplicate_policy: Optional[str] = None,
36 ):
37 """
38 Create a new time-series.
39
40 Args:
41
42 key:
43 time-series key
44 retention_msecs:
45 Maximum age for samples compared to highest reported timestamp (in milliseconds).
46 If None or 0 is passed then the series is not trimmed at all.
47 uncompressed:
48 Changes data storage from compressed (by default) to uncompressed
49 labels:
50 Set of label-value pairs that represent metadata labels of the key.
51 chunk_size:
52 Memory size, in bytes, allocated for each data chunk.
53 Must be a multiple of 8 in the range [128 .. 1048576].
54 duplicate_policy:
55 Policy for handling multiple samples with identical timestamps.
56 Can be one of:
57 - 'block': an error will occur for any out of order sample.
58 - 'first': ignore the new value.
59 - 'last': override with latest value.
60 - 'min': only override if the value is less than the existing value.
61 - 'max': only override if the value is greater than the existing value.
62 - 'sum': If a previous sample exists, add the new sample to it so that \
63 the updated value is equal to (previous + new). If no previous sample \
64 exists, set the updated value equal to the new value.
65
66 For more information: https://valkey.io/commands/ts.create/
67 """ # noqa
68 params = [key]
69 self._append_retention(params, retention_msecs)
70 self._append_uncompressed(params, uncompressed)
71 self._append_chunk_size(params, chunk_size)
72 self._append_duplicate_policy(params, CREATE_CMD, duplicate_policy)
73 self._append_labels(params, labels)
74
75 return self.execute_command(CREATE_CMD, *params)
76
77 def alter(
78 self,
79 key: KeyT,
80 retention_msecs: Optional[int] = None,
81 labels: Optional[Dict[str, str]] = None,
82 chunk_size: Optional[int] = None,
83 duplicate_policy: Optional[str] = None,
84 ):
85 """
86 Update the retention, chunk size, duplicate policy, and labels of an existing
87 time series.
88
89 Args:
90
91 key:
92 time-series key
93 retention_msecs:
94 Maximum retention period, compared to maximal existing timestamp (in milliseconds).
95 If None or 0 is passed then the series is not trimmed at all.
96 labels:
97 Set of label-value pairs that represent metadata labels of the key.
98 chunk_size:
99 Memory size, in bytes, allocated for each data chunk.
100 Must be a multiple of 8 in the range [128 .. 1048576].
101 duplicate_policy:
102 Policy for handling multiple samples with identical timestamps.
103 Can be one of:
104 - 'block': an error will occur for any out of order sample.
105 - 'first': ignore the new value.
106 - 'last': override with latest value.
107 - 'min': only override if the value is less than the existing value.
108 - 'max': only override if the value is greater than the existing value.
109 - 'sum': If a previous sample exists, add the new sample to it so that \
110 the updated value is equal to (previous + new). If no previous sample \
111 exists, set the updated value equal to the new value.
112
113 For more information: https://valkey.io/commands/ts.alter/
114 """ # noqa
115 params = [key]
116 self._append_retention(params, retention_msecs)
117 self._append_chunk_size(params, chunk_size)
118 self._append_duplicate_policy(params, ALTER_CMD, duplicate_policy)
119 self._append_labels(params, labels)
120
121 return self.execute_command(ALTER_CMD, *params)
122
123 def add(
124 self,
125 key: KeyT,
126 timestamp: Union[int, str],
127 value: Number,
128 retention_msecs: Optional[int] = None,
129 uncompressed: Optional[bool] = False,
130 labels: Optional[Dict[str, str]] = None,
131 chunk_size: Optional[int] = None,
132 duplicate_policy: Optional[str] = None,
133 ):
134 """
135 Append (or create and append) a new sample to a time series.
136
137 Args:
138
139 key:
140 time-series key
141 timestamp:
142 Timestamp of the sample. * can be used for automatic timestamp (using the system clock).
143 value:
144 Numeric data value of the sample
145 retention_msecs:
146 Maximum retention period, compared to maximal existing timestamp (in milliseconds).
147 If None or 0 is passed then the series is not trimmed at all.
148 uncompressed:
149 Changes data storage from compressed (by default) to uncompressed
150 labels:
151 Set of label-value pairs that represent metadata labels of the key.
152 chunk_size:
153 Memory size, in bytes, allocated for each data chunk.
154 Must be a multiple of 8 in the range [128 .. 1048576].
155 duplicate_policy:
156 Policy for handling multiple samples with identical timestamps.
157 Can be one of:
158 - 'block': an error will occur for any out of order sample.
159 - 'first': ignore the new value.
160 - 'last': override with latest value.
161 - 'min': only override if the value is less than the existing value.
162 - 'max': only override if the value is greater than the existing value.
163 - 'sum': If a previous sample exists, add the new sample to it so that \
164 the updated value is equal to (previous + new). If no previous sample \
165 exists, set the updated value equal to the new value.
166
167 For more information: https://valkey.io/commands/ts.add/
168 """ # noqa
169 params = [key, timestamp, value]
170 self._append_retention(params, retention_msecs)
171 self._append_uncompressed(params, uncompressed)
172 self._append_chunk_size(params, chunk_size)
173 self._append_duplicate_policy(params, ADD_CMD, duplicate_policy)
174 self._append_labels(params, labels)
175
176 return self.execute_command(ADD_CMD, *params)
177
178 def madd(self, ktv_tuples: List[Tuple[KeyT, Union[int, str], Number]]):
179 """
180 Append (or create and append) a new `value` to series
181 `key` with `timestamp`.
182 Expects a list of `tuples` as (`key`,`timestamp`, `value`).
183 Return value is an array with timestamps of insertions.
184
185 For more information: https://valkey.io/commands/ts.madd/
186 """ # noqa
187 params = []
188 for ktv in ktv_tuples:
189 params.extend(ktv)
190
191 return self.execute_command(MADD_CMD, *params)
192
193 def incrby(
194 self,
195 key: KeyT,
196 value: Number,
197 timestamp: Optional[Union[int, str]] = None,
198 retention_msecs: Optional[int] = None,
199 uncompressed: Optional[bool] = False,
200 labels: Optional[Dict[str, str]] = None,
201 chunk_size: Optional[int] = None,
202 ):
203 """
204 Increment (or create a time-series and increment) the latest sample's of a series.
205 This command can be used as a counter or gauge that automatically gets history as a time series.
206
207 Args:
208
209 key:
210 time-series key
211 value:
212 Numeric data value of the sample
213 timestamp:
214 Timestamp of the sample. * can be used for automatic timestamp (using the system clock).
215 retention_msecs:
216 Maximum age for samples compared to last event time (in milliseconds).
217 If None or 0 is passed then the series is not trimmed at all.
218 uncompressed:
219 Changes data storage from compressed (by default) to uncompressed
220 labels:
221 Set of label-value pairs that represent metadata labels of the key.
222 chunk_size:
223 Memory size, in bytes, allocated for each data chunk.
224
225 For more information: https://valkey.io/commands/ts.incrby/
226 """ # noqa
227 params = [key, value]
228 self._append_timestamp(params, timestamp)
229 self._append_retention(params, retention_msecs)
230 self._append_uncompressed(params, uncompressed)
231 self._append_chunk_size(params, chunk_size)
232 self._append_labels(params, labels)
233
234 return self.execute_command(INCRBY_CMD, *params)
235
236 def decrby(
237 self,
238 key: KeyT,
239 value: Number,
240 timestamp: Optional[Union[int, str]] = None,
241 retention_msecs: Optional[int] = None,
242 uncompressed: Optional[bool] = False,
243 labels: Optional[Dict[str, str]] = None,
244 chunk_size: Optional[int] = None,
245 ):
246 """
247 Decrement (or create a time-series and decrement) the latest sample's of a series.
248 This command can be used as a counter or gauge that automatically gets history as a time series.
249
250 Args:
251
252 key:
253 time-series key
254 value:
255 Numeric data value of the sample
256 timestamp:
257 Timestamp of the sample. * can be used for automatic timestamp (using the system clock).
258 retention_msecs:
259 Maximum age for samples compared to last event time (in milliseconds).
260 If None or 0 is passed then the series is not trimmed at all.
261 uncompressed:
262 Changes data storage from compressed (by default) to uncompressed
263 labels:
264 Set of label-value pairs that represent metadata labels of the key.
265 chunk_size:
266 Memory size, in bytes, allocated for each data chunk.
267
268 For more information: https://valkey.io/commands/ts.decrby/
269 """ # noqa
270 params = [key, value]
271 self._append_timestamp(params, timestamp)
272 self._append_retention(params, retention_msecs)
273 self._append_uncompressed(params, uncompressed)
274 self._append_chunk_size(params, chunk_size)
275 self._append_labels(params, labels)
276
277 return self.execute_command(DECRBY_CMD, *params)
278
279 def delete(self, key: KeyT, from_time: int, to_time: int):
280 """
281 Delete all samples between two timestamps for a given time series.
282
283 Args:
284
285 key:
286 time-series key.
287 from_time:
288 Start timestamp for the range deletion.
289 to_time:
290 End timestamp for the range deletion.
291
292 For more information: https://valkey.io/commands/ts.del/
293 """ # noqa
294 return self.execute_command(DEL_CMD, key, from_time, to_time)
295
296 def createrule(
297 self,
298 source_key: KeyT,
299 dest_key: KeyT,
300 aggregation_type: str,
301 bucket_size_msec: int,
302 align_timestamp: Optional[int] = None,
303 ):
304 """
305 Create a compaction rule from values added to `source_key` into `dest_key`.
306
307 Args:
308
309 source_key:
310 Key name for source time series
311 dest_key:
312 Key name for destination (compacted) time series
313 aggregation_type:
314 Aggregation type: One of the following:
315 [`avg`, `sum`, `min`, `max`, `range`, `count`, `first`, `last`, `std.p`,
316 `std.s`, `var.p`, `var.s`, `twa`]
317 bucket_size_msec:
318 Duration of each bucket, in milliseconds
319 align_timestamp:
320 Assure that there is a bucket that starts at exactly align_timestamp and
321 align all other buckets accordingly.
322
323 For more information: https://valkey.io/commands/ts.createrule/
324 """ # noqa
325 params = [source_key, dest_key]
326 self._append_aggregation(params, aggregation_type, bucket_size_msec)
327 if align_timestamp is not None:
328 params.append(align_timestamp)
329
330 return self.execute_command(CREATERULE_CMD, *params)
331
332 def deleterule(self, source_key: KeyT, dest_key: KeyT):
333 """
334 Delete a compaction rule from `source_key` to `dest_key`..
335
336 For more information: https://valkey.io/commands/ts.deleterule/
337 """ # noqa
338 return self.execute_command(DELETERULE_CMD, source_key, dest_key)
339
340 def __range_params(
341 self,
342 key: KeyT,
343 from_time: Union[int, str],
344 to_time: Union[int, str],
345 count: Optional[int],
346 aggregation_type: Optional[str],
347 bucket_size_msec: Optional[int],
348 filter_by_ts: Optional[List[int]],
349 filter_by_min_value: Optional[int],
350 filter_by_max_value: Optional[int],
351 align: Optional[Union[int, str]],
352 latest: Optional[bool],
353 bucket_timestamp: Optional[str],
354 empty: Optional[bool],
355 ):
356 """Create TS.RANGE and TS.REVRANGE arguments."""
357 params = [key, from_time, to_time]
358 self._append_latest(params, latest)
359 self._append_filer_by_ts(params, filter_by_ts)
360 self._append_filer_by_value(params, filter_by_min_value, filter_by_max_value)
361 self._append_count(params, count)
362 self._append_align(params, align)
363 self._append_aggregation(params, aggregation_type, bucket_size_msec)
364 self._append_bucket_timestamp(params, bucket_timestamp)
365 self._append_empty(params, empty)
366
367 return params
368
369 def range(
370 self,
371 key: KeyT,
372 from_time: Union[int, str],
373 to_time: Union[int, str],
374 count: Optional[int] = None,
375 aggregation_type: Optional[str] = None,
376 bucket_size_msec: Optional[int] = 0,
377 filter_by_ts: Optional[List[int]] = None,
378 filter_by_min_value: Optional[int] = None,
379 filter_by_max_value: Optional[int] = None,
380 align: Optional[Union[int, str]] = None,
381 latest: Optional[bool] = False,
382 bucket_timestamp: Optional[str] = None,
383 empty: Optional[bool] = False,
384 ):
385 """
386 Query a range in forward direction for a specific time-series.
387
388 Args:
389
390 key:
391 Key name for timeseries.
392 from_time:
393 Start timestamp for the range query. - can be used to express the minimum possible timestamp (0).
394 to_time:
395 End timestamp for range query, + can be used to express the maximum possible timestamp.
396 count:
397 Limits the number of returned samples.
398 aggregation_type:
399 Optional aggregation type. Can be one of [`avg`, `sum`, `min`, `max`,
400 `range`, `count`, `first`, `last`, `std.p`, `std.s`, `var.p`, `var.s`, `twa`]
401 bucket_size_msec:
402 Time bucket for aggregation in milliseconds.
403 filter_by_ts:
404 List of timestamps to filter the result by specific timestamps.
405 filter_by_min_value:
406 Filter result by minimum value (must mention also filter by_max_value).
407 filter_by_max_value:
408 Filter result by maximum value (must mention also filter by_min_value).
409 align:
410 Timestamp for alignment control for aggregation.
411 latest:
412 Used when a time series is a compaction, reports the compacted value of the
413 latest possibly partial bucket
414 bucket_timestamp:
415 Controls how bucket timestamps are reported. Can be one of [`-`, `low`, `+`,
416 `high`, `~`, `mid`].
417 empty:
418 Reports aggregations for empty buckets.
419
420 For more information: https://valkey.io/commands/ts.range/
421 """ # noqa
422 params = self.__range_params(
423 key,
424 from_time,
425 to_time,
426 count,
427 aggregation_type,
428 bucket_size_msec,
429 filter_by_ts,
430 filter_by_min_value,
431 filter_by_max_value,
432 align,
433 latest,
434 bucket_timestamp,
435 empty,
436 )
437 return self.execute_command(RANGE_CMD, *params, keys=[key])
438
439 def revrange(
440 self,
441 key: KeyT,
442 from_time: Union[int, str],
443 to_time: Union[int, str],
444 count: Optional[int] = None,
445 aggregation_type: Optional[str] = None,
446 bucket_size_msec: Optional[int] = 0,
447 filter_by_ts: Optional[List[int]] = None,
448 filter_by_min_value: Optional[int] = None,
449 filter_by_max_value: Optional[int] = None,
450 align: Optional[Union[int, str]] = None,
451 latest: Optional[bool] = False,
452 bucket_timestamp: Optional[str] = None,
453 empty: Optional[bool] = False,
454 ):
455 """
456 Query a range in reverse direction for a specific time-series.
457
458 **Note**: This command is only available since RedisTimeSeries >= v1.4
459
460 Args:
461
462 key:
463 Key name for timeseries.
464 from_time:
465 Start timestamp for the range query. - can be used to express the minimum possible timestamp (0).
466 to_time:
467 End timestamp for range query, + can be used to express the maximum possible timestamp.
468 count:
469 Limits the number of returned samples.
470 aggregation_type:
471 Optional aggregation type. Can be one of [`avg`, `sum`, `min`, `max`,
472 `range`, `count`, `first`, `last`, `std.p`, `std.s`, `var.p`, `var.s`, `twa`]
473 bucket_size_msec:
474 Time bucket for aggregation in milliseconds.
475 filter_by_ts:
476 List of timestamps to filter the result by specific timestamps.
477 filter_by_min_value:
478 Filter result by minimum value (must mention also filter_by_max_value).
479 filter_by_max_value:
480 Filter result by maximum value (must mention also filter_by_min_value).
481 align:
482 Timestamp for alignment control for aggregation.
483 latest:
484 Used when a time series is a compaction, reports the compacted value of the
485 latest possibly partial bucket
486 bucket_timestamp:
487 Controls how bucket timestamps are reported. Can be one of [`-`, `low`, `+`,
488 `high`, `~`, `mid`].
489 empty:
490 Reports aggregations for empty buckets.
491
492 For more information: https://valkey.io/commands/ts.revrange/
493 """ # noqa
494 params = self.__range_params(
495 key,
496 from_time,
497 to_time,
498 count,
499 aggregation_type,
500 bucket_size_msec,
501 filter_by_ts,
502 filter_by_min_value,
503 filter_by_max_value,
504 align,
505 latest,
506 bucket_timestamp,
507 empty,
508 )
509 return self.execute_command(REVRANGE_CMD, *params, keys=[key])
510
511 def __mrange_params(
512 self,
513 aggregation_type: Optional[str],
514 bucket_size_msec: Optional[int],
515 count: Optional[int],
516 filters: List[str],
517 from_time: Union[int, str],
518 to_time: Union[int, str],
519 with_labels: Optional[bool],
520 filter_by_ts: Optional[List[int]],
521 filter_by_min_value: Optional[int],
522 filter_by_max_value: Optional[int],
523 groupby: Optional[str],
524 reduce: Optional[str],
525 select_labels: Optional[List[str]],
526 align: Optional[Union[int, str]],
527 latest: Optional[bool],
528 bucket_timestamp: Optional[str],
529 empty: Optional[bool],
530 ):
531 """Create TS.MRANGE and TS.MREVRANGE arguments."""
532 params = [from_time, to_time]
533 self._append_latest(params, latest)
534 self._append_filer_by_ts(params, filter_by_ts)
535 self._append_filer_by_value(params, filter_by_min_value, filter_by_max_value)
536 self._append_with_labels(params, with_labels, select_labels)
537 self._append_count(params, count)
538 self._append_align(params, align)
539 self._append_aggregation(params, aggregation_type, bucket_size_msec)
540 self._append_bucket_timestamp(params, bucket_timestamp)
541 self._append_empty(params, empty)
542 params.extend(["FILTER"])
543 params += filters
544 self._append_groupby_reduce(params, groupby, reduce)
545 return params
546
547 def mrange(
548 self,
549 from_time: Union[int, str],
550 to_time: Union[int, str],
551 filters: List[str],
552 count: Optional[int] = None,
553 aggregation_type: Optional[str] = None,
554 bucket_size_msec: Optional[int] = 0,
555 with_labels: Optional[bool] = False,
556 filter_by_ts: Optional[List[int]] = None,
557 filter_by_min_value: Optional[int] = None,
558 filter_by_max_value: Optional[int] = None,
559 groupby: Optional[str] = None,
560 reduce: Optional[str] = None,
561 select_labels: Optional[List[str]] = None,
562 align: Optional[Union[int, str]] = None,
563 latest: Optional[bool] = False,
564 bucket_timestamp: Optional[str] = None,
565 empty: Optional[bool] = False,
566 ):
567 """
568 Query a range across multiple time-series by filters in forward direction.
569
570 Args:
571
572 from_time:
573 Start timestamp for the range query. `-` can be used to express the minimum possible timestamp (0).
574 to_time:
575 End timestamp for range query, `+` can be used to express the maximum possible timestamp.
576 filters:
577 filter to match the time-series labels.
578 count:
579 Limits the number of returned samples.
580 aggregation_type:
581 Optional aggregation type. Can be one of [`avg`, `sum`, `min`, `max`,
582 `range`, `count`, `first`, `last`, `std.p`, `std.s`, `var.p`, `var.s`, `twa`]
583 bucket_size_msec:
584 Time bucket for aggregation in milliseconds.
585 with_labels:
586 Include in the reply all label-value pairs representing metadata labels of the time series.
587 filter_by_ts:
588 List of timestamps to filter the result by specific timestamps.
589 filter_by_min_value:
590 Filter result by minimum value (must mention also filter_by_max_value).
591 filter_by_max_value:
592 Filter result by maximum value (must mention also filter_by_min_value).
593 groupby:
594 Grouping by fields the results (must mention also reduce).
595 reduce:
596 Applying reducer functions on each group. Can be one of [`avg` `sum`, `min`,
597 `max`, `range`, `count`, `std.p`, `std.s`, `var.p`, `var.s`].
598 select_labels:
599 Include in the reply only a subset of the key-value pair labels of a series.
600 align:
601 Timestamp for alignment control for aggregation.
602 latest:
603 Used when a time series is a compaction, reports the compacted
604 value of the latest possibly partial bucket
605 bucket_timestamp:
606 Controls how bucket timestamps are reported. Can be one of [`-`, `low`, `+`,
607 `high`, `~`, `mid`].
608 empty:
609 Reports aggregations for empty buckets.
610
611 For more information: https://valkey.io/commands/ts.mrange/
612 """ # noqa
613 params = self.__mrange_params(
614 aggregation_type,
615 bucket_size_msec,
616 count,
617 filters,
618 from_time,
619 to_time,
620 with_labels,
621 filter_by_ts,
622 filter_by_min_value,
623 filter_by_max_value,
624 groupby,
625 reduce,
626 select_labels,
627 align,
628 latest,
629 bucket_timestamp,
630 empty,
631 )
632
633 return self.execute_command(MRANGE_CMD, *params)
634
635 def mrevrange(
636 self,
637 from_time: Union[int, str],
638 to_time: Union[int, str],
639 filters: List[str],
640 count: Optional[int] = None,
641 aggregation_type: Optional[str] = None,
642 bucket_size_msec: Optional[int] = 0,
643 with_labels: Optional[bool] = False,
644 filter_by_ts: Optional[List[int]] = None,
645 filter_by_min_value: Optional[int] = None,
646 filter_by_max_value: Optional[int] = None,
647 groupby: Optional[str] = None,
648 reduce: Optional[str] = None,
649 select_labels: Optional[List[str]] = None,
650 align: Optional[Union[int, str]] = None,
651 latest: Optional[bool] = False,
652 bucket_timestamp: Optional[str] = None,
653 empty: Optional[bool] = False,
654 ):
655 """
656 Query a range across multiple time-series by filters in reverse direction.
657
658 Args:
659
660 from_time:
661 Start timestamp for the range query. - can be used to express the minimum possible timestamp (0).
662 to_time:
663 End timestamp for range query, + can be used to express the maximum possible timestamp.
664 filters:
665 Filter to match the time-series labels.
666 count:
667 Limits the number of returned samples.
668 aggregation_type:
669 Optional aggregation type. Can be one of [`avg`, `sum`, `min`, `max`,
670 `range`, `count`, `first`, `last`, `std.p`, `std.s`, `var.p`, `var.s`, `twa`]
671 bucket_size_msec:
672 Time bucket for aggregation in milliseconds.
673 with_labels:
674 Include in the reply all label-value pairs representing metadata labels of the time series.
675 filter_by_ts:
676 List of timestamps to filter the result by specific timestamps.
677 filter_by_min_value:
678 Filter result by minimum value (must mention also filter_by_max_value).
679 filter_by_max_value:
680 Filter result by maximum value (must mention also filter_by_min_value).
681 groupby:
682 Grouping by fields the results (must mention also reduce).
683 reduce:
684 Applying reducer functions on each group. Can be one of [`avg` `sum`, `min`,
685 `max`, `range`, `count`, `std.p`, `std.s`, `var.p`, `var.s`].
686 select_labels:
687 Include in the reply only a subset of the key-value pair labels of a series.
688 align:
689 Timestamp for alignment control for aggregation.
690 latest:
691 Used when a time series is a compaction, reports the compacted
692 value of the latest possibly partial bucket
693 bucket_timestamp:
694 Controls how bucket timestamps are reported. Can be one of [`-`, `low`, `+`,
695 `high`, `~`, `mid`].
696 empty:
697 Reports aggregations for empty buckets.
698
699 For more information: https://valkey.io/commands/ts.mrevrange/
700 """ # noqa
701 params = self.__mrange_params(
702 aggregation_type,
703 bucket_size_msec,
704 count,
705 filters,
706 from_time,
707 to_time,
708 with_labels,
709 filter_by_ts,
710 filter_by_min_value,
711 filter_by_max_value,
712 groupby,
713 reduce,
714 select_labels,
715 align,
716 latest,
717 bucket_timestamp,
718 empty,
719 )
720
721 return self.execute_command(MREVRANGE_CMD, *params)
722
723 def get(self, key: KeyT, latest: Optional[bool] = False):
724 """# noqa
725 Get the last sample of `key`.
726 `latest` used when a time series is a compaction, reports the compacted
727 value of the latest (possibly partial) bucket
728
729 For more information: https://valkey.io/commands/ts.get/
730 """ # noqa
731 params = [key]
732 self._append_latest(params, latest)
733 return self.execute_command(GET_CMD, *params, keys=[key])
734
735 def mget(
736 self,
737 filters: List[str],
738 with_labels: Optional[bool] = False,
739 select_labels: Optional[List[str]] = None,
740 latest: Optional[bool] = False,
741 ):
742 """# noqa
743 Get the last samples matching the specific `filter`.
744
745 Args:
746
747 filters:
748 Filter to match the time-series labels.
749 with_labels:
750 Include in the reply all label-value pairs representing metadata
751 labels of the time series.
752 select_labels:
753 Include in the reply only a subset of the key-value pair labels of a series.
754 latest:
755 Used when a time series is a compaction, reports the compacted
756 value of the latest possibly partial bucket
757
758 For more information: https://valkey.io/commands/ts.mget/
759 """ # noqa
760 params = []
761 self._append_latest(params, latest)
762 self._append_with_labels(params, with_labels, select_labels)
763 params.extend(["FILTER"])
764 params += filters
765 return self.execute_command(MGET_CMD, *params)
766
767 def info(self, key: KeyT):
768 """# noqa
769 Get information of `key`.
770
771 For more information: https://valkey.io/commands/ts.info/
772 """ # noqa
773 return self.execute_command(INFO_CMD, key, keys=[key])
774
775 def queryindex(self, filters: List[str]):
776 """# noqa
777 Get all time series keys matching the `filter` list.
778
779 For more information: https://valkey.io/commands/ts.queryindex/
780 """ # noq
781 return self.execute_command(QUERYINDEX_CMD, *filters)
782
783 @staticmethod
784 def _append_uncompressed(params: List[str], uncompressed: Optional[bool]):
785 """Append UNCOMPRESSED tag to params."""
786 if uncompressed:
787 params.extend(["UNCOMPRESSED"])
788
789 @staticmethod
790 def _append_with_labels(
791 params: List[str],
792 with_labels: Optional[bool],
793 select_labels: Optional[List[str]],
794 ):
795 """Append labels behavior to params."""
796 if with_labels and select_labels:
797 raise DataError(
798 "with_labels and select_labels cannot be provided together."
799 )
800
801 if with_labels:
802 params.extend(["WITHLABELS"])
803 if select_labels:
804 params.extend(["SELECTED_LABELS", *select_labels])
805
806 @staticmethod
807 def _append_groupby_reduce(
808 params: List[str], groupby: Optional[str], reduce: Optional[str]
809 ):
810 """Append GROUPBY REDUCE property to params."""
811 if groupby is not None and reduce is not None:
812 params.extend(["GROUPBY", groupby, "REDUCE", reduce.upper()])
813
814 @staticmethod
815 def _append_retention(params: List[str], retention: Optional[int]):
816 """Append RETENTION property to params."""
817 if retention is not None:
818 params.extend(["RETENTION", retention])
819
820 @staticmethod
821 def _append_labels(params: List[str], labels: Optional[List[str]]):
822 """Append LABELS property to params."""
823 if labels:
824 params.append("LABELS")
825 for k, v in labels.items():
826 params.extend([k, v])
827
828 @staticmethod
829 def _append_count(params: List[str], count: Optional[int]):
830 """Append COUNT property to params."""
831 if count is not None:
832 params.extend(["COUNT", count])
833
834 @staticmethod
835 def _append_timestamp(params: List[str], timestamp: Optional[int]):
836 """Append TIMESTAMP property to params."""
837 if timestamp is not None:
838 params.extend(["TIMESTAMP", timestamp])
839
840 @staticmethod
841 def _append_align(params: List[str], align: Optional[Union[int, str]]):
842 """Append ALIGN property to params."""
843 if align is not None:
844 params.extend(["ALIGN", align])
845
846 @staticmethod
847 def _append_aggregation(
848 params: List[str],
849 aggregation_type: Optional[str],
850 bucket_size_msec: Optional[int],
851 ):
852 """Append AGGREGATION property to params."""
853 if aggregation_type is not None:
854 params.extend(["AGGREGATION", aggregation_type, bucket_size_msec])
855
856 @staticmethod
857 def _append_chunk_size(params: List[str], chunk_size: Optional[int]):
858 """Append CHUNK_SIZE property to params."""
859 if chunk_size is not None:
860 params.extend(["CHUNK_SIZE", chunk_size])
861
862 @staticmethod
863 def _append_duplicate_policy(
864 params: List[str], command: Optional[str], duplicate_policy: Optional[str]
865 ):
866 """Append DUPLICATE_POLICY property to params on CREATE
867 and ON_DUPLICATE on ADD.
868 """
869 if duplicate_policy is not None:
870 if command == "TS.ADD":
871 params.extend(["ON_DUPLICATE", duplicate_policy])
872 else:
873 params.extend(["DUPLICATE_POLICY", duplicate_policy])
874
875 @staticmethod
876 def _append_filer_by_ts(params: List[str], ts_list: Optional[List[int]]):
877 """Append FILTER_BY_TS property to params."""
878 if ts_list is not None:
879 params.extend(["FILTER_BY_TS", *ts_list])
880
881 @staticmethod
882 def _append_filer_by_value(
883 params: List[str], min_value: Optional[int], max_value: Optional[int]
884 ):
885 """Append FILTER_BY_VALUE property to params."""
886 if min_value is not None and max_value is not None:
887 params.extend(["FILTER_BY_VALUE", min_value, max_value])
888
889 @staticmethod
890 def _append_latest(params: List[str], latest: Optional[bool]):
891 """Append LATEST property to params."""
892 if latest:
893 params.append("LATEST")
894
895 @staticmethod
896 def _append_bucket_timestamp(params: List[str], bucket_timestamp: Optional[str]):
897 """Append BUCKET_TIMESTAMP property to params."""
898 if bucket_timestamp is not None:
899 params.extend(["BUCKETTIMESTAMP", bucket_timestamp])
900
901 @staticmethod
902 def _append_empty(params: List[str], empty: Optional[bool]):
903 """Append EMPTY property to params."""
904 if empty:
905 params.append("EMPTY")