redis-time-series 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d699daec01bb891952501de6a51cc4b966be74a0f8585030bafb4f6a908b36e
-  data.tar.gz: dfa027d344c4d5485b0a22a33edd67973c2a60cb60dbbaa1a57101ccce8833fc
+  metadata.gz: 58671cce77efea0c1b4f405e60dcd73cb3f01101fabdb0cb9bc8b11335392116
+  data.tar.gz: b9c7e56687b5eb7d5286a88990ca20c5d82f6857070ab953e6d74925d5cbefb6
 SHA512:
-  metadata.gz: acadcad9c6919e810f0e100bfe20b60055507e2efa98d0853fca6c15a252f99b65c722c71acc99d37d8d9f72964d91f862c9604fb96458ca3faaddce9f841752
-  data.tar.gz: 489415e8247d8cffefcf13e4e70c82cde752170c4416bc0973495c5d38b1d27d2b554cdd62db8729c9c71b125cb4848aa5a1efd81b998aa5f6e5683c13be8ccc
+  metadata.gz: 402de8f815ef0ff2dfe9426d6be2e68508093c3a35d7def4721f5bfe9ba3a9b52d8b375600302b989c24fc10b4d9c7bc43249a81715267112fa4776d8429ea18
+  data.tar.gz: 3c6a554173d5f9c4a92a77c65c8c8fed8035395b3066ff0cbf222e1983347645fbabf1e498516218a042c3a3c0ad7d157ab5e39b1e22971a73189a5e3aba9496

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.4.0
+* Added [hash-based filter DSL](https://github.com/dzunk/redis-time-series/tree/7173c73588da50614c02f9c89bf2ecef77766a78#filter-dsl)
+* Removed `Time#ts_msec` monkey-patch
+* Renamed `TimeSeries.queryindex` to `.query_index`
+* Added `TS.CREATERULE` and `TS.DELETERULE` commands
+* Renamed `InvalidFilters` to `FilterError`
+
 ## 0.3.0
 * Added `TS.QUERYINDEX` command
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    redis-time-series (0.3.0)
+    redis-time-series (0.4.0)
       redis (~> 4.0)
 
 GEM

data/README.md

@@ -162,23 +162,92 @@ ts.size
 ```
 Find series matching specific label(s)
 ```ruby
-Redis::TimeSeries.queryindex('foo=bar')
+Redis::TimeSeries.query_index('foo=bar')
 => [#<Redis::TimeSeries:0x00007fc115ba1610
   @key="ts3",
   @redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>,
   @retention=nil,
   @uncompressed=false>]
 # Note that you need at least one "label equals value" filter
-Redis::TimeSeries.queryindex('foo!=bar')
+Redis::TimeSeries.query_index('foo!=bar')
 => RuntimeError: Filtering requires at least one equality comparison
+# query_index is also aliased as .where for fluency
+Redis::TimeSeries.where('foo=bar')
+=> [#<Redis::TimeSeries:0x00007fb8981010c8
+  @key="ts3",
+  @redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>,
+  @retention=nil,
+  @uncompressed=false>]
+```
+### Filter DSL
+You can provide filter strings directly, per the time series documentation.
+```ruby
+Redis::TimeSeries.where('foo=bar')
+=> [#<Redis::TimeSeries:0x00007fb8981010c8...>]
+```
+There is also a hash-based syntax available, which may be more pleasant to work with.
+```ruby
+Redis::TimeSeries.where(foo: 'bar')
+=> [#<Redis::TimeSeries:0x00007fb89811dca0...>]
+```
+All six filter types are represented in hash format below.
+```ruby
+{
+  foo: 'bar',          # label=value  (equality)
+  foo: { not: 'bar' }, # label!=value (inequality)
+  foo: true,           # label=       (presence)
+  foo: false,          # label!=      (absence)
+  foo: [1, 2],         # label=(1,2)  (any value)
+  foo: { not: [1, 2] } # label!=(1,2) (no values)
+}
+```
+Note the special use of `true` and `false`. If you're representing a boolean value with a label, rather than setting its value to "true" or "false" (which would be treated as strings in Redis anyway), you should add or remove the label from the series.
+
+Values can be any object that responds to `.to_s`:
+```ruby
+class Person
+  def initialize(name)
+    @name = name
+  end
+
+  def to_s
+    @name
+  end
+end
+
+Redis::TimeSeries.where(person: Person.new('John'))
+#=> TS.QUERYINDEX person=John
+```
+
+### Compaction Rules
+Add a compaction rule to a series.
+```ruby
+# `dest` needs to be created before the rule is added.
+other_ts = Redis::TimeSeries.create('other_ts')
+
+# Note: aggregation durations are measured in milliseconds
+ts.create_rule(dest: other_ts, aggregation: [:count, 6000])
+
+# Can also provide a string key instead of a time series object
+ts.create_rule(dest: 'other_ts', aggregation: [:avg, 120000])
+
+# Can also provide an Aggregation object instead of an array
+agg = Redis::TimeSeries::Aggregation.new(:avg, 120000)
+ts.create_rule(dest: other_ts, aggregation: agg)
+
+# Class-level method also available
+Redis::TimeSeries.create_rule(source: ts, dest: other_ts, aggregation: ['std.p', 150000])
+```
+Remove an existing compaction rule
+```ruby
+ts.delete_rule(dest: 'other_ts')
+Redis::TimeSeries.delete_rule(source: ts, dest: 'other_ts')
 ```
 
 
 ### TODO
 * `TS.REVRANGE`
 * `TS.MRANGE`/`TS.MREVRANGE`
-* Compaction rules
-* Filters
 * Probably a bunch more stuff
 
 ## Development

data/lib/ext/time_msec.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+module TimeMsec
+  refine Time do
+    def ts_msec
+      (to_f * 1000.0).to_i
+    end
+  end
+end

data/lib/redis-time-series.rb

@@ -1,11 +1,13 @@
 require 'bigdecimal'
 require 'forwardable'
-require 'time/msec'
-require 'redis/time_series/filter'
+require 'ext/time_msec'
+require 'redis/time_series/errors'
+require 'redis/time_series/aggregation'
+require 'redis/time_series/filters'
 require 'redis/time_series/info'
 require 'redis/time_series/sample'
 require 'redis/time_series'
 
 class RedisTimeSeries
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/lib/redis/time_series.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
+using TimeMsec
+
 class Redis
   class TimeSeries
     extend Forwardable
@@ -8,6 +10,27 @@ class Redis
         new(key, **options).create(labels: options[:labels])
       end
 
+      def create_rule(source:, dest:, aggregation:)
+        args = [
+          source.is_a?(self) ? source.key : source.to_s,
+          dest.is_a?(self) ? dest.key : dest.to_s,
+          Aggregation.parse(aggregation).to_a
+        ]
+        redis.call 'TS.CREATERULE', *args.flatten
+      end
+
+      def delete_rule(source:, dest:)
+        args = [
+          source.is_a?(self) ? source.key : source.to_s,
+          dest.is_a?(self) ? dest.key : dest.to_s
+        ]
+        redis.call 'TS.DELETERULE', *args
+      end
+
+      def destroy(key)
+        redis.del key
+      end
+
       def madd(data)
         data.reduce([]) do |memo, (key, value)|
           if value.is_a?(Hash) || (value.is_a?(Array) && value.first.is_a?(Array))
@@ -33,11 +56,13 @@ class Redis
         end
       end
 
-      def queryindex(filter_value)
-        filters = Filter.new(filter_value)
+      def query_index(filter_value)
+        filters = Filters.new(filter_value)
         filters.validate!
+        puts "DEBUG: TS.QUERYINDEX #{filters.to_a.join(' ')}" if ENV['DEBUG']
         redis.call('TS.QUERYINDEX', *filters.to_a).map { |key| new(key) }
       end
+      alias where query_index
 
       def redis
         @redis ||= Redis.current
@@ -72,6 +97,14 @@ class Redis
       self
     end
 
+    def create_rule(dest:, aggregation:)
+      self.class.create_rule(source: self, dest: dest, aggregation: aggregation)
+    end
+
+    def delete_rule(dest:)
+      self.class.delete_rule(source: self, dest: dest)
+    end
+
     def decrby(value = 1, timestamp = nil)
       args = [key, value]
       args << timestamp if timestamp

data/lib/redis/time_series/aggregation.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+class Redis
+  class TimeSeries
+    class Aggregation
+      TYPES = %w[
+        avg
+        count
+        first
+        last
+        max
+        min
+        range
+        std.p
+        std.s
+        sum
+        var.p
+        var.s
+      ]
+
+      attr_reader :type, :duration
+
+      alias aggregation_type type
+      alias time_bucket duration
+
+      def self.parse(agg)
+        return agg if agg.is_a?(self)
+        return new(agg.first, agg.last) if agg.is_a?(Array) && agg.size == 2
+        raise AggregationError, "Couldn't parse #{agg} into an aggregation rule!"
+      end
+
+      def initialize(type, duration)
+        unless TYPES.include? type.to_s
+          raise AggregationError, "#{type} is not a valid aggregation type!"
+        end
+        @type = type.to_s
+        @duration = duration.to_i
+      end
+
+      def to_a
+        ['AGGREGATION', type, duration]
+      end
+
+      def to_s
+        to_a.join(' ')
+      end
+
+      def ==(other)
+        parsed = self.class.parse(other)
+        type == parsed.type && duration == parsed.duration
+      end
+    end
+  end
+end

data/lib/redis/time_series/errors.rb

@@ -0,0 +1,15 @@
+class Redis
+  class TimeSeries
+    # Base error class for convenient `rescue`ing
+    class Error < StandardError; end
+
+    # Invalid filter error is raised when attempting to filter without at least
+    # one equality comparison ("foo=bar")
+    class FilterError < Error; end
+
+    # Aggregation error is raised when attempting to create anaggreation with
+    # an unknown type, or when calling a command with an invalid aggregation value.
+    # @see Redis::TimeSeries::Aggregation
+    class AggregationError < Error; end
+  end
+end

data/lib/redis/time_series/{filter.rb → filters.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 class Redis
   class TimeSeries
-    class Filter
+    class Filters
       Equal = Struct.new(:label, :value) do
         self::REGEX = /^[^!]+=[^(]+/
 
@@ -9,6 +9,10 @@ class Redis
           new(*str.split('='))
         end
 
+        def to_h
+          { label => value }
+        end
+
         def to_s
           "#{label}=#{value}"
         end
@@ -21,6 +25,10 @@ class Redis
           new(*str.split('!='))
         end
 
+        def to_h
+          { label => { not: value } }
+        end
+
         def to_s
           "#{label}!=#{value}"
         end
@@ -33,6 +41,10 @@ class Redis
           new(str.delete('='))
         end
 
+        def to_h
+          { label => false }
+        end
+
         def to_s
           "#{label}="
         end
@@ -45,6 +57,10 @@ class Redis
           new(str.delete('!='))
         end
 
+        def to_h
+          { label => true }
+        end
+
         def to_s
           "#{label}!="
         end
@@ -59,8 +75,12 @@ class Redis
           new(label, values)
         end
 
+        def to_h
+          { label => values }
+        end
+
         def to_s
-          "#{label}=(#{values.join(',')})"
+          "#{label}=(#{values.map(&:to_s).join(',')})"
         end
       end
 
@@ -73,14 +93,18 @@ class Redis
           new(label, values)
         end
 
+        def to_h
+          { label => { not: values } }
+        end
+
         def to_s
-          "#{label}!=(#{values.join(',')})"
+          "#{label}!=(#{values.map(&:to_s).join(',')})"
         end
       end
 
       TYPES = [Equal, NotEqual, Absent, Present, AnyValue, NoValues]
       TYPES.each do |type|
-        define_method "#{type.to_s.split('::').last.gsub(/(.)([A-Z])/,'\1_\2').downcase}_filters" do
+        define_method "#{type.to_s.split('::').last.gsub(/(.)([A-Z])/,'\1_\2').downcase}" do
           filters.select { |f| f.is_a? type }
         end
       end
@@ -88,12 +112,15 @@ class Redis
       attr_reader :filters
 
       def initialize(filters = nil)
-        filters = parse_string(filters) if filters.is_a?(String)
-        @filters = filters.presence || {}
+        @filters = case filters
+                   when String then parse_string(filters)
+                   when Hash then parse_hash(filters)
+                   else []
+                   end
       end
 
       def validate!
-        valid? || raise('Filtering requires at least one equality comparison')
+        valid? || raise(FilterError, 'Filtering requires at least one equality comparison')
       end
 
       def valid?
@@ -104,15 +131,39 @@ class Redis
         filters.map(&:to_s)
       end
 
+      def to_h
+        filters.reduce({}) { |h, filter| h.merge(filter.to_h) }
+      end
+
+      def to_s
+        to_a.join(' ')
+      end
+
       private
 
       def parse_string(filter_string)
+        return unless filter_string.is_a? String
         filter_string.split(' ').map do |str|
           match = TYPES.find { |f| f::REGEX.match? str }
-          raise "Unable to parse '#{str}'" unless match
+          raise(FilterError, "Unable to parse '#{str}'") unless match
           match.parse(str)
         end
       end
+
+      def parse_hash(filter_hash)
+        return unless filter_hash.is_a? Hash
+        filter_hash.map do |label, value|
+          case value
+          when TrueClass then Present.new(label)
+          when FalseClass then Absent.new(label)
+          when Array then AnyValue.new(label, value)
+          when Hash
+            raise(FilterError, "Invalid filter hash value #{value}") unless value.keys === [:not]
+            (v = value.values.first).is_a?(Array) ? NoValues.new(label, v) : NotEqual.new(label, v)
+          else Equal.new(label, value)
+          end
+        end
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis-time-series
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Duszynski
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-07-17 00:00:00.000000000 Z
+date: 2020-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -112,12 +112,14 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- lib/ext/time_msec.rb
 - lib/redis-time-series.rb
 - lib/redis/time_series.rb
-- lib/redis/time_series/filter.rb
+- lib/redis/time_series/aggregation.rb
+- lib/redis/time_series/errors.rb
+- lib/redis/time_series/filters.rb
 - lib/redis/time_series/info.rb
 - lib/redis/time_series/sample.rb
-- lib/time/msec.rb
 - redis-time-series.gemspec
 homepage: https://github.com/dzunk/redis-time-series
 licenses:

data/lib/time/msec.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-class Time
-  # TODO: use refinemenets instead of monkey-patching Time
-  def ts_msec
-    (to_f * 1000.0).to_i
-  end
-end