redis-time-series 0.3.0 → 0.6.0

data/lib/redis/time_series/aggregation.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+class Redis
+  class TimeSeries
+    # An aggregation is a combination of a mathematical function, and a time window over
+    # which to apply that function. In RedisTimeSeries, aggregations are used to downsample
+    # data from a source series to a destination series, using compaction rules.
+    #
+    # @see Redis::TimeSeries#create_rule
+    # @see Redis::TimeSeries::Rule
+    # @see https://oss.redislabs.com/redistimeseries/commands/#aggregation-compaction-downsampling
+    class Aggregation
+      TYPES = %w[
+        avg
+        count
+        first
+        last
+        max
+        min
+        range
+        std.p
+        std.s
+        sum
+        var.p
+        var.s
+      ]
+
+      # @return [String] the type of aggregation to apply
+      # @see TYPES
+      attr_reader :type
+      alias aggregation_type type
+
+      # @return [Integer] the time window to apply the aggregation over, in milliseconds
+      attr_reader :duration
+      alias time_bucket duration
+
+      # Parse a method argument into an aggregation.
+      #
+      # @param agg [Array, Aggregation] an aggregation object, or an array of type and duration +[:avg, 60000]+
+      # @return [Aggregation] the parsed aggregation, or the original argument if already an aggregation
+      # @raise [AggregationError] when given an unparseable value
+      def self.parse(agg)
+        return unless 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
+
+      # Create a new Aggregation given a type and duration.
+      # @param type [String, Symbol] one of the valid aggregation {TYPES}
+      # @param duration [Integer, ActiveSupport::Duration]
+      #   A time window to apply this aggregation over.
+      #   If you're using ActiveSupport, duration objects (e.g. +10.minutes+) will be automatically coerced.
+      # @return [Aggregation]
+      # @raise [AggregationError] if the given aggregation type is not valid
+      def initialize(type, duration)
+        type = type.to_s.downcase
+        unless TYPES.include? type
+          raise AggregationError, "#{type} is not a valid aggregation type!"
+        end
+        @type = type
+        if defined?(ActiveSupport::Duration) && duration.is_a?(ActiveSupport::Duration)
+          @duration = duration.in_milliseconds
+        else
+          @duration = duration.to_i
+        end
+      end
+
+      # @api private
+      # @return [Array]
+      def to_a
+        ['AGGREGATION', type, duration]
+      end
+
+      # @api private
+      # @return [String]
+      def to_s
+        to_a.join(' ')
+      end
+
+      # Compares aggregations based on type and duration.
+      # @return [Boolean] whether the given aggregations are equivalent
+      def ==(other)
+        parsed = self.class.parse(other)
+        type == parsed.type && duration == parsed.duration
+      end
+    end
+  end
+end

data/lib/redis/time_series/client.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+using TimeMsec
+
+class Redis
+  class TimeSeries
+    # The client module handles connection management for individual time series, and
+    # the parent {TimeSeries} class methods. You can enable or disable debugging, and set
+    # a default Redis client to use for time series objects.
+    module Client
+      def self.extended(base)
+        base.class_eval do
+          attr_reader :redis
+
+          private
+
+          def cmd(name, *args)
+            self.class.send :cmd_with_redis, redis, name, *args
+          end
+        end
+      end
+
+      # Check debug status. Defaults to on with +DEBUG=true+ environment variable.
+      # @return [Boolean] current debug status
+      def debug
+        @debug.nil? ? [true, 'true', 1].include?(ENV['DEBUG']) : @debug
+      end
+
+      # Enable or disable debug output for time series commands. Enabling debug will
+      # print commands to +STDOUT+ as they're executed.
+      #
+      # @example
+      #   [1] pry(main)> @ts1.get
+      #   => #<Redis::TimeSeries::Sample:0x00007fc82e9de150 @time=2020-07-19 15:01:13 -0700, @value=0.56e2>
+      #   [2] pry(main)> Redis::TimeSeries.debug = true
+      #   => true
+      #   [3] pry(main)> @ts1.get
+      #   DEBUG: TS.GET ts1
+      #    => #<Redis::TimeSeries::Sample:0x00007fc82f11b7b0 @time=2020-07-19 15:01:13 -0700, @value=0.56e2>
+      #
+      # @return [Boolean] new debug status
+      def debug=(bool)
+        @debug = !!bool
+      end
+
+      # @return [Redis] the current Redis client. Defaults to +Redis.current+
+      def redis
+        @redis ||= Redis.current
+      end
+
+      # Set the default Redis client for time series objects.
+      # This may be useful if you already use a non-time-series Redis database, and want
+      # to use both at the same time.
+      #
+      # @example
+      #   # config/initializers/redis_time_series.rb
+      #   Redis::TimeSeries.redis = Redis.new(url: 'redis://my-redis-server:6379/0')
+      #
+      # @param client [Redis] a Redis client
+      # @return [Redis]
+      def redis=(client)
+        @redis = client
+      end
+
+      private
+
+      def cmd(name, *args)
+        cmd_with_redis redis, name, *args
+      end
+
+      def cmd_with_redis(redis, name, *args)
+        args = args.flatten.compact.map { |arg| arg.is_a?(Time) ? arg.ts_msec : arg }
+        puts "DEBUG: #{name} #{args.join(' ')}" if debug
+        redis.call name, args
+      end
+    end
+  end
+end

data/lib/redis/time_series/duplicate_policy.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+class Redis
+  class TimeSeries
+    # Duplication policies can be applied to a time series in order to resolve conflicts
+    # when adding data that already exists in the series.
+    #
+    # @see https://oss.redislabs.com/redistimeseries/master/configuration/#duplicate_policy
+    class DuplicatePolicy
+      VALID_POLICIES = %i[
+        block
+        first
+        last
+        min
+        max
+        sum
+      ].freeze
+
+      attr_reader :policy
+
+      def initialize(policy)
+        policy = policy.to_s.downcase.to_sym
+        if VALID_POLICIES.include?(policy)
+          @policy = policy
+        else
+          raise UnknownPolicyError, "#{policy} is not a valid duplicate policy"
+        end
+      end
+
+      def to_a(cmd = 'DUPLICATE_POLICY')
+        [cmd, policy]
+      end
+
+      def to_s(cmd = 'DUPLICATE_POLICY')
+        to_a(cmd).join(' ')
+      end
+
+      def ==(other)
+        return policy == other.policy if other.is_a?(self.class)
+        policy == self.class.new(other).policy
+      end
+
+      VALID_POLICIES.each do |policy|
+        define_method("#{policy}?") do
+          @policy == policy
+        end
+      end
+    end
+  end
+end

data/lib/redis/time_series/errors.rb

@@ -0,0 +1,24 @@
+class Redis
+  class TimeSeries
+    # Base error class for convenient +rescue+-ing.
+    #
+    # Descendant of +Redis::BaseError+, so you can rescue that and capture all
+    # time-series errors, as well as standard Redis command errors.
+    class Error < Redis::BaseError; end
+
+    # +FilterError+ is raised when a given set of filters is invalid (i.e. does not contain
+    # a equality comparison "foo=bar"), or the filter value is unparseable.
+    # @see Redis::TimeSeries::Filters
+    class FilterError < Error; end
+
+    # +AggregationError+ is raised when attempting to create an aggreation with
+    # an unknown type, or when calling a command with an invalid aggregation value.
+    # @see Redis::TimeSeries::Aggregation
+    class AggregationError < Error; end
+
+    # +UnknownPolicyError+ is raised when attempting to apply an unkown type of
+    # duplicate policy when creating or adding to a series.
+    # @see Redis::TimeSeries::DuplicatePolicy
+    class UnknownPolicyError < 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

data/lib/redis/time_series/info.rb

@@ -1,28 +1,110 @@
 # frozen_string_literal: true
 class Redis
   class TimeSeries
+    # The Info struct wraps the result of the +TS.INFO+ command with method access.
+    # It also applies some limited parsing to the result values, mainly snakifying
+    # the property keys, and instantiating Rule objects if necessary.
+    #
+    # All properties of the struct are also available on a TimeSeries object itself
+    # via delegation.
+    #
+    # @!attribute [r] chunk_count
+    #   @return [Integer] number of memory chunks used for the time-series
+    # @!attribute [r] chunk_size
+    #   @return [Integer] amount of allocated memory in bytes
+    # @!attribute [r] chunk_type
+    #   @return [String] whether the chunk is "compressed" or "uncompressed"
+    # @!attribute [r] first_timestamp
+    #   @return [Integer] first timestamp present in the time-series (milliseconds since epoch)
+    # @!attribute [r] labels
+    #   @return [Hash] a hash of label-value pairs that represent metadata labels of the time-series
+    # @!attribute [r] last_timestamp
+    #   @return [Integer] last timestamp present in the time-series (milliseconds since epoch)
+    # @!attribute [r] max_samples_per_chunk
+    #   @return [Integer] maximum number of samples per memory chunk
+    # @!attribute [r] memory_usage
+    #   @return [Integer] total number of bytes allocated for the time-series
+    # @!attribute [r] retention_time
+    #   @return [Integer] retention time, in milliseconds, for the time-series.
+    #     A zero value means unlimited retention.
+    # @!attribute [r] rules
+    #   @return [Array<Rule>] an array of configured compaction {Rule}s
+    # @!attribute [r] series
+    #   @return [TimeSeries] the series this info is from
+    # @!attribute [r] source_key
+    #   @return [String, nil] the key of the source series, if this series is the destination
+    #     of a compaction rule
+    # @!attribute [r] total_samples
+    #   @return [Integer] the total number of samples in the series
+    #
+    # @see TimeSeries#info
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsinfo
     Info = Struct.new(
-      :total_samples,
-      :memory_usage,
+      :chunk_count,
+      :chunk_size,
+      :chunk_type,
+      :duplicate_policy,
       :first_timestamp,
+      :labels,
       :last_timestamp,
-      :retention_time,
-      :chunk_count,
       :max_samples_per_chunk,
-      :labels,
-      :source_key,
+      :memory_usage,
+      :retention_time,
       :rules,
+      :series,
+      :source_key,
+      :total_samples,
       keyword_init: true
     ) do
-      def self.parse(raw_array)
-        raw_array.each_slice(2).reduce({}) do |h, (key, value)|
-          # Convert camelCase info keys to snake_case
-          h[key.gsub(/(.)([A-Z])/,'\1_\2').downcase] = value
-          h
-        end.then do |parsed_hash|
-          parsed_hash['labels'] = parsed_hash['labels'].to_h
-          new(parsed_hash)
+      class << self
+        # @api private
+        # @return [Info]
+        def parse(series:, data:)
+          build_hash(data)
+            .merge(series: series)
+            .then(&method(:parse_labels))
+            .then(&method(:parse_policies))
+            .then(&method(:parse_rules))
+            .then(&method(:new))
+        end
+
+        private
+
+        def build_hash(data)
+          data.each_slice(2).reduce({}) do |h, (key, value)|
+            # Convert camelCase info keys to snake_case
+            key = key.gsub(/(.)([A-Z])/,'\1_\2').downcase.to_sym
+            # Skip unknown properties
+            next h unless members.include?(key)
+            h.merge(key => value)
+          end
         end
+
+        def parse_labels(hash)
+          hash[:labels] = hash[:labels].to_h.transform_values { |v| v.to_i.to_s == v ? v.to_i : v }
+          hash
+        end
+
+        def parse_policies(hash)
+          hash[:duplicate_policy] = DuplicatePolicy.new(hash[:duplicate_policy]) if hash[:duplicate_policy]
+          hash
+        end
+
+        def parse_rules(hash)
+          hash[:rules] = hash[:rules].map { |d| Rule.new(source: hash[:series], data: d) }
+          hash
+        end
+      end
+
+      alias count total_samples
+      alias length total_samples
+      alias size total_samples
+
+      # If this series is the destination of a compaction rule, returns the source series of the data.
+      # @return [TimeSeries, nil] the series referred to by {source_key}
+      def source
+        return unless source_key
+        @source ||= TimeSeries.new(source_key, redis: series.redis)
       end
     end
   end