redis-time-series 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4648678522434687a6e278490c7a308c64f6460394b8ebde16b2ce2daa9e92ad
-  data.tar.gz: e2f48fb1c8efebb3b4d6e4c47d1d86137a10ac8a54735c94b3bdb35ef6396651
+  metadata.gz: 400fac8affe8b6c5acbc7892bd9704fb39da3135929451ce282ad43278f698ff
+  data.tar.gz: 70a10d9ca8cd01e8b113e6b769008ccb0e9a167cbd16777773d2df8d8a41d2c2
 SHA512:
-  metadata.gz: 269a787d8d2a2a467a52e915ab717bc5b20eb28cacc55eb5dfc9ce3909a7d83cdd4e15b19afc92612d19fa551c6ba793df76ceef03d8bb8bdb16b6dc0253d2cc
-  data.tar.gz: c5d845052ca8f2a518fb3a20a82a8d8aa35128cb824f54d2531a949767e90f8c7979ede07ba1bd56ae30a825edb9f6be90e52ca404a14199bfd13484026d8d40
+  metadata.gz: 7b166b6d74161936686e1f0d8d6d5b27238414036b16fc8c4537cc02a2848734b8bf26a183820069b7ad662d45465fc38e6fc1c307dbc543c028a746a30d5024
+  data.tar.gz: 3f3f178d267e261e9c3ee17b50fff7e5826d231bf9051364c070727af13841a6118596c255857bf750973445a9860cbbeaa007001425f602d409381dd24a851f

data/.github/workflows/rspec.yml

@@ -12,9 +12,10 @@ jobs:
   spec:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         image_version: ['latest', 'edge']
-        ruby_version: ['2.6', '2.7']
+        ruby_version: ['2.6', '2.7', '3.0', '3.1']
     services:
       redis:
         image: redislabs/redistimeseries:${{ matrix.image_version }}

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.7.0
+* Add Ruby 3.1 to build matrix (#70)
+* Add Ruby 3.0 to build matrix (#63)
+* Relax Redis version constraint (#62)
+* Add TS.REVRANGE, TS.MRANGE, and TS.MREVRANGE commands (#19)
+* Update TS.MADD commands to consolidate parsing (#58)
+
 ## 0.6.0
 * Add CHUNK_SIZE param to CREATE, ADD, INCRBY, DECRBY commands (#53)
 * Add duplication policy to TS.CREATE and TS.ADD commands (#51)

data/README.md

@@ -24,7 +24,7 @@ ts.add 56
 => #<Redis::TimeSeries::Sample:0x00007f8c0d26c460 @time=2020-06-25 23:23:16 -0700, @value=0.56e2>
 ts.add 78
 => #<Redis::TimeSeries::Sample:0x00007f8c0d276618 @time=2020-06-25 23:23:20 -0700, @value=0.78e2>
-ts.range (Time.now.to_i - 100)..Time.now.to_i
+ts.range (Time.now.to_i - 100)..Time.now.to_i * 1000
 => [#<Redis::TimeSeries::Sample:0x00007f8c0d297200 @time=2020-06-25 23:23:04 -0700, @value=0.1234e4>,
  #<Redis::TimeSeries::Sample:0x00007f8c0d297048 @time=2020-06-25 23:23:16 -0700, @value=0.56e2>,
  #<Redis::TimeSeries::Sample:0x00007f8c0d296e90 @time=2020-06-25 23:23:20 -0700, @value=0.78e2>]
@@ -213,6 +213,38 @@ Redis::TimeSeries.where('foo=bar')
   @retention=nil,
   @uncompressed=false>]
 ```
+
+### Querying Multiple Series
+Get all samples from matching series over a time range with `mrange`
+```ruby
+[4] pry(main)> result = Redis::TimeSeries.mrange(1.minute.ago.., filter: { foo: 'bar' })
+=> [#<struct Redis::TimeSeries::Multi::Result
+  series=
+   #<Redis::TimeSeries:0x00007f833e408ad0
+    @key="ts3",
+    @redis=#<Redis client v4.2.5 for redis://127.0.0.1:6379/0>>,
+  labels=[],
+  samples=
+   [#<Redis::TimeSeries::Sample:0x00007f833e408a58
+     @time=2021-06-17 20:58:33 3246391/4194304 -0700,
+     @value=0.1e1>,
+    #<Redis::TimeSeries::Sample:0x00007f833e408850
+     @time=2021-06-17 20:58:33 413139/524288 -0700,
+     @value=0.3e1>,
+    #<Redis::TimeSeries::Sample:0x00007f833e408670
+     @time=2021-06-17 20:58:33 1679819/2097152 -0700,
+     @value=0.2e1>]>]
+[5] pry(main)> result.keys
+=> ["ts3"]
+[6] pry(main)> result['ts3'].values
+=> [0.1e1, 0.3e1, 0.2e1]
+```
+Order them from newest to oldest with `mrevrange`
+```ruby
+[8] pry(main)> Redis::TimeSeries.mrevrange(1.minute.ago.., filter: { foo: 'bar' }).first.values
+=> [0.2e1, 0.3e1, 0.1e1]
+```
+
 ### Filter DSL
 You can provide filter strings directly, per the time series documentation.
 ```ruby
@@ -299,11 +331,8 @@ ts.rules.first.delete
 Redis::TimeSeries.delete_rule(source: ts, dest: 'other_ts')
 ```
 
-
 ### TODO
-* `TS.REVRANGE`
-* `TS.MRANGE`/`TS.MREVRANGE`
-* Probably a bunch more stuff
+* Check the [open issues](https://github.com/dzunk/redis-time-series/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) on Github.
 
 ## Development
 

data/lib/redis/time_series/multi.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+class Redis
+  class TimeSeries
+    # A {Multi} is a collection of multiple series and their samples, returned
+    # from a multi command (e.g. TS.MGET or TS.MRANGE).
+    #
+    # @see TimeSeries.mrange
+    # @see TimeSeries.mrevrange
+    class Multi < DelegateClass(Array)
+      # Multis are initialized by one of the class-level query commands.
+      # There's no need to ever create one yourself.
+      # @api private
+      def initialize(result_array)
+        super(result_array.map do |res|
+          Result.new(
+            TimeSeries.new(res[0]),
+            res[1],
+            res[2].map { |s| Sample.new(s[0], s[1]) }
+          )
+        end)
+      end
+
+      # Access a specific result by either array position, or hash lookup.
+      #
+      # @param index_or_key [Integer, String] The integer position, or series
+      #   key, of the specific result to return.
+      # @return [Multi::Result, nil] A single series result, or nil if there is
+      #   no matching series.
+      def [](index_or_key)
+        return super if index_or_key.is_a?(Integer)
+        find { |result| result.series.key == index_or_key.to_s }
+      end
+
+      # Get all the series keys that are present in this result collection.
+      # @return [Array<String>] An array of the series keys in these results.
+      def keys
+        map { |r| r.series.key }
+      end
+
+      # Get all the series objects that are present in this result collection.
+      # @return [Array<TimeSeries>] An array of the series in these results.
+      def series
+        map(&:series)
+      end
+
+      # Convert these results into a hash, keyed by series name.
+      # @return [Hash<Array>] A hash of series names and samples.
+      # @example
+      #   {"ts3"=>
+      #     [{:timestamp=>1623945216042, :value=>0.1e1},
+      #      {:timestamp=>1623945216055, :value=>0.3e1},
+      #      {:timestamp=>1623945216069, :value=>0.2e1}]}
+      def to_h
+        super do |result|
+          [result.series.key, result.samples.map(&:to_h)]
+        end
+      end
+
+      # Get a count of all matching samples from all series in this result collection.
+      # @return [Integer] The total size of all samples from all series in these results.
+      def sample_count
+        reduce(0) { |size, r| size += r.samples.size }
+      end
+
+      Result = Struct.new(:series, :labels, :samples) do
+        def values
+          samples.map(&:value)
+        end
+      end
+    end
+  end
+end

data/lib/redis/time_series/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 class Redis
   class TimeSeries
-    VERSION = '0.6.0'
+    VERSION = '0.7.0'
   end
 end

data/lib/redis/time_series.rb

@@ -41,7 +41,8 @@ class Redis
       #   A duplication policy to resolve conflicts when adding values to the series.
       #   Valid values are in Redis::TimeSeries::DuplicatePolicy::VALID_POLICIES
       # @option options [Integer] :chunk_size
-      #   Amount of memory, in bytes, to allocate for each chunk of data
+      #   Amount of memory, in bytes, to allocate for each chunk of data. Must be a multiple
+      #   of 8. Default for a series is 4096.
       #
       # @return [Redis::TimeSeries] the created time series
       # @see https://oss.redislabs.com/redistimeseries/commands/#tscreate
@@ -88,6 +89,23 @@ class Redis
         redis.del key
       end
 
+      # Add multiple values to multiple series.
+      #
+      # @example Adding multiple values with timestamps
+      #   Redis::TimeSeries.madd(
+      #     foo: { 2.minutes.ago => 123, 1.minute.ago => 456, Time.current => 789) },
+      #     bar: { 2.minutes.ago => 987, 1.minute.ago => 654, Time.current => 321) }
+      #   )
+      # @example Adding multiple values without timestamps
+      #   Redis::TimeSeries.madd(foo: 1, bar: 2, baz: 3)
+      #
+      # @param data [Hash] A hash of key-value pairs, with the key being the name of
+      #   the series, and the value being a single scalar value or a nested hash
+      #   of timestamp => value pairs
+      # @return [Array<Sample, Redis::CommandError>] an array of the resulting samples
+      #   added, or a CommandError if the sample in question could not be added to the
+      #   series
+      #
       def madd(data)
         data.reduce([]) do |memo, (key, value)|
           memo << parse_madd_values(key, value)
@@ -98,6 +116,46 @@ class Redis
           end
         end
       end
+      alias multi_add madd
+      alias add_multiple madd
+
+      # Query across multiple series, returning values from oldest to newest.
+      #
+      # @param range [Range] A time range over which to query. Beginless and endless ranges
+      #   indicate oldest and most recent timestamp, respectively.
+      # @param filter [Hash, String] a set of filters to query with. Refer to the {Filters}
+      #   documentation for more details on how to filter.
+      # @param count [Integer] The maximum number of results to return for each series.
+      # @param aggregation [Array(<String, Symbol>, Integer), Aggregation]
+      #   The aggregation to apply. Can be an {Aggregation} object, or an array of
+      #   aggregation_type and duration +[:avg, 120000]+
+      # @param with_labels [Boolean] Whether to return the label details of the matched
+      #   series in the result object.
+      # @return [Multi] A multi-series collection of results
+      #
+      # @see https://oss.redislabs.com/redistimeseries/commands/#tsmrangetsmrevrange
+      def mrange(range, filter:, count: nil, aggregation: nil, with_labels: false)
+        multi_cmd('TS.MRANGE', range, filter, count, aggregation, with_labels)
+      end
+
+      # Query across multiple series, returning values from newest to oldest.
+      #
+      # @param range [Range] A time range over which to query. Beginless and endless ranges
+      #   indicate oldest and most recent timestamp, respectively.
+      # @param filter [Hash, String] a set of filters to query with. Refer to the {Filters}
+      #   documentation for more details on how to filter.
+      # @param count [Integer] The maximum number of results to return for each series.
+      # @param aggregation [Array(<String, Symbol>, Integer), Aggregation]
+      #   The aggregation to apply. Can be an {Aggregation} object, or an array of
+      #   aggregation_type and duration +[:avg, 120000]+
+      # @param with_labels [Boolean] Whether to return the label details of the matched
+      #   series in the result object.
+      # @return [Multi] A multi-series collection of results
+      #
+      # @see https://oss.redislabs.com/redistimeseries/commands/#tsmrangetsmrevrange
+      def mrevrange(range, filter:, count: nil, aggregation: nil, with_labels: false)
+        multi_cmd('TS.MREVRANGE', range, filter, count, aggregation, with_labels)
+      end
 
       # Search for a time series matching the provided filters. Refer to the {Filters} documentation
       # for more details on how to filter.
@@ -124,19 +182,36 @@ class Redis
 
       private
 
+      def multi_cmd(cmd_name, range, filter, count, agg, with_labels)
+        filters = Filters.new(filter)
+        filters.validate!
+        cmd(
+          cmd_name,
+          (range.begin || '-'),
+          (range.end || '+'),
+          (['COUNT', count] if count),
+          Aggregation.parse(agg)&.to_a,
+          ('WITHLABELS' if with_labels),
+          ['FILTER', filters.to_a]
+        ).then { |response| Multi.new(response) }
+      end
+
       def key_for(series_or_string)
         series_or_string.is_a?(self) ? series_or_string.key : series_or_string.to_s
       end
 
       def parse_madd_values(key, raw)
-        if raw.is_a?(Hash) || (raw.is_a?(Array) && raw.first.is_a?(Array))
+        if raw.is_a? Hash
           # multiple timestamp => value pairs
           raw.map do |timestamp, value|
             [key, timestamp, value]
           end
         elsif raw.is_a? Array
-          # single [timestamp, value]
-          [key, raw.first, raw.last]
+          # multiple values, no timestamps
+          now = Time.now.ts_msec
+          raw.each_with_index.map do |value, index|
+            [key, now + index, value]
+          end
         else
           # single value, no timestamp
           [key, '*', raw]
@@ -301,32 +376,30 @@ class Redis
       cmd 'TS.ALTER', key, 'LABELS', val.to_a
     end
 
-    def madd(*values)
-      if values.one? && values.first.is_a?(Hash)
-        # Hash of timestamp => value pairs
-        args = values.first.map do |ts, val|
-          [key, ts, val]
-        end.flatten
-      elsif values.one? && values.first.is_a?(Array)
-        # Array of values, no timestamps
-        initial_ts = Time.now.ts_msec
-        args = values.first.each_with_index.map do |val, idx|
-          [key, initial_ts + idx, val]
-        end.flatten
-      else
-        # Values as individual arguments, no timestamps
-        initial_ts = Time.now.ts_msec
-        args = values.each_with_index.map do |val, idx|
-          [key, initial_ts + idx, val]
-        end.flatten
+    # Add multiple values to the series.
+    #
+    # @example Adding multiple values with timestamps
+    #   ts.madd(2.minutes.ago => 987, 1.minute.ago => 654, Time.current => 321)
+    #
+    # @param data [Hash] A hash of key-value pairs, with the key being a Time
+    #   object or integer timestamp, and the value being a single scalar value
+    # @return [Array<Sample, Redis::CommandError>] an array of the resulting samples
+    #   added, or a CommandError if the sample in question could not be added to the
+    #   series
+    #
+    def madd(data)
+      args = self.class.send(:parse_madd_values, key, data)
+      cmd('TS.MADD', args).each_with_index.map do |result, idx|
+        result.is_a?(Redis::CommandError) ? result : Sample.new(result, args[idx][2])
       end
-      # TODO: return Sample objects here
-      cmd 'TS.MADD', args
     end
+    alias multi_add madd
+    alias add_multiple madd
 
-    # Get a range of values from the series
+    # Get a range of values from the series, from earliest to most recent
     #
-    # @param range [Hash, Range] a time range, or hash of +from+ and +to+ values
+    # @param range [Range] A time range over which to query. Beginless and endless ranges
+    #   indicate oldest and most recent timestamp, respectively.
     # @param count [Integer] the maximum number of results to return
     # @param aggregation [Array(<String, Symbol>, Integer), Aggregation]
     #   The aggregation to apply. Can be an {Aggregation} object, or an array of
@@ -336,20 +409,23 @@ class Redis
     #
     # @see https://oss.redislabs.com/redistimeseries/commands/#tsrangetsrevrange
     def range(range, count: nil, aggregation: nil)
-      if range.is_a?(Hash)
-        # This is to support from: and to: passed in as hash keys
-        # `range` will swallow all parameters if they're all hash syntax
-        count = range.delete(:count)
-        aggregation = range.delete(:aggregation)
-        range = range.fetch(:from)..range[:to]
-      end
-      cmd('TS.RANGE',
-          key,
-          (range.begin || '-'),
-          (range.end || '+'),
-          (['COUNT', count] if count),
-          Aggregation.parse(aggregation)&.to_a
-         ).map { |ts, val| Sample.new(ts, val) }
+      range_cmd('TS.RANGE', range, count, aggregation)
+    end
+
+    # Get a range of values from the series, from most recent to earliest
+    #
+    # @param range [Range] A time range over which to query. Beginless and endless ranges
+    #   indicate oldest and most recent timestamp, respectively.
+    # @param count [Integer] the maximum number of results to return
+    # @param aggregation [Array(<String, Symbol>, Integer), Aggregation]
+    #   The aggregation to apply. Can be an {Aggregation} object, or an array of
+    #   aggregation_type and duration +[:avg, 120000]+
+    #
+    # @return [Array<Sample>] an array of samples matching the range query
+    #
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsrangetsrevrange
+    def revrange(range, count: nil, aggregation: nil)
+      range_cmd('TS.REVRANGE', range, count, aggregation)
     end
 
     # Set data retention time for the series using +TS.ALTER+
@@ -369,5 +445,17 @@ class Redis
       return false unless other.is_a?(self.class)
       key == other.key && redis == other.redis
     end
+
+    private
+
+    def range_cmd(cmd_name, range, count, agg)
+      cmd(cmd_name,
+          key,
+          (range.begin || '-'),
+          (range.end || '+'),
+          (['COUNT', count] if count),
+          Aggregation.parse(agg)&.to_a
+         ).map { |ts, val| Sample.new(ts, val) }
+    end
   end
 end

data/lib/redis-time-series.rb

@@ -7,6 +7,7 @@ require 'redis/time_series/errors'
 require 'redis/time_series/aggregation'
 require 'redis/time_series/duplicate_policy'
 require 'redis/time_series/filters'
+require 'redis/time_series/multi'
 require 'redis/time_series/rule'
 require 'redis/time_series/info'
 require 'redis/time_series/sample'

data/redis-time-series.gemspec

@@ -31,10 +31,10 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'redis', '>= 3.3', '< 5'
+  spec.add_dependency 'redis', '>= 3.3'
 
   spec.add_development_dependency 'activesupport', '~> 6.0'
-  spec.add_development_dependency 'appraisal'
+  spec.add_development_dependency 'appraisal', '>= 2.4.1'
   spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'pry', '~> 0.13'
   spec.add_development_dependency 'rake', '~> 13.0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis-time-series
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Matt Duszynski
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-12-20 00:00:00.000000000 Z
+date: 2022-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -17,9 +17,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.3'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -27,9 +24,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.3'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '5'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -50,14 +44,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.4.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.4.1
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -155,6 +149,7 @@ files:
 - lib/redis/time_series/errors.rb
 - lib/redis/time_series/filters.rb
 - lib/redis/time_series/info.rb
+- lib/redis/time_series/multi.rb
 - lib/redis/time_series/rule.rb
 - lib/redis/time_series/sample.rb
 - lib/redis/time_series/version.rb
@@ -181,7 +176,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.2
+rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
 summary: A Ruby adapter for the RedisTimeSeries module.