redis-time-series 0.1.1 → 0.5.1

data/lib/ext/time_msec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# The +TimeMsec+ module is a refinement for the +Time+ class that makes it easier
+# to work with millisecond timestamps.
+#
+# @example
+#   Time.now.to_i    # 1595194259
+#   Time.now.ts_msec # NoMethodError
+#
+#   using TimeMsec
+#
+#   Time.now.to_i    # 1595194259
+#   Time.now.ts_msec # 1595194259000
+#
+#   Time.from_msec(1595194259000) # 2020-07-19 14:30:59 -0700
+module TimeMsec
+  refine Time do
+    # TODO: convert to #to_msec
+    def ts_msec
+      (to_f * 1000.0).to_i
+    end
+  end
+
+  refine Time.singleton_class do
+    def from_msec(timestamp)
+      at(timestamp / 1000.0)
+    end
+  end
+end

data/lib/redis-time-series.rb

@@ -1,8 +1,13 @@
 require 'bigdecimal'
-require 'time/msec'
-require 'redis/time_series'
+require 'forwardable'
+require 'ext/time_msec'
+require 'redis/time_series/client'
+require 'redis/time_series/errors'
+require 'redis/time_series/aggregation'
+require 'redis/time_series/filters'
+require 'redis/time_series/rule'
+require 'redis/time_series/info'
 require 'redis/time_series/sample'
+require 'redis/time_series'
 
-class RedisTimeSeries
-  VERSION = '0.1.1'
-end
+class RedisTimeSeries; end

data/lib/redis/time_series.rb

@@ -1,82 +1,234 @@
 # frozen_string_literal: true
+using TimeMsec
+
 class Redis
+  # The +Redis::TimeSeries+ class is an interface for working with time-series data in
+  # Redis, using the {https://oss.redislabs.com/redistimeseries RedisTimeSeries} module.
+  #
+  # You can't use this gem with vanilla Redis, the time series module must be compiled
+  # and loaded. The easiest way to do this is by running the provided Docker container.
+  # Refer to the {https://oss.redislabs.com/redistimeseries/#setup setup guide} for more info.
+  #
+  # +docker run -p 6379:6379 -it --rm redislabs/redistimeseries+
+  #
+  # Once you're up and running, you can create a new time series and start recording data.
+  # Many commands are documented below, but you should refer to the
+  # {https://oss.redislabs.com/redistimeseries/commands command documentation} for the most
+  # authoritative and up-to-date reference.
+  #
+  # @example
+  #   ts = Redis::TimeSeries.create('time_series_example')
+  #   ts.add(12345)
+  #   ts.get
+  #   #=> #<Redis::TimeSeries::Sample:0x00007ff00d942e60 @time=2020-07-19 16:52:48 -0700, @value=0.12345e5>
   class TimeSeries
+    extend Client
+    extend Forwardable
+
     class << self
+      # Create a new time series.
+      #
+      # @param key [String] the Redis key to store time series data in
+      # @option options [Hash] :labels
+      #   A hash of label-value pairs to apply to this series.
+      # @option options [Redis] :redis (self.class.redis) a different Redis client to use
+      # @option options [Integer] :retention
+      #   Maximum age for samples compared to last event time (in milliseconds).
+      #   With no value, the series will not be trimmed.
+      # @option options [Boolean] :uncompressed
+      #   When true, series data will be stored in an uncompressed format.
+      #
+      # @return [Redis::TimeSeries] the created time series
+      # @see https://oss.redislabs.com/redistimeseries/commands/#tscreate
       def create(key, **options)
-        new(key, **options).create
+        new(key, redis: options.fetch(:redis, redis)).create(**options)
+      end
+
+      # Create a compaction rule for a series. Note that both source and destination series
+      # must exist before the rule can be created.
+      #
+      # @param source [String, TimeSeries] the source series (or key) to apply the rule to
+      # @param dest [String, TimeSeries] the destination series (or key) to aggregate the data
+      # @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 [String] the string "OK"
+      # @raise [Redis::TimeSeries::AggregationError] if the given aggregation params are invalid
+      # @raise [Redis::CommandError] if the compaction rule cannot be applied to either series
+      #
+      # @see TimeSeries#create_rule
+      # @see https://oss.redislabs.com/redistimeseries/commands/#tscreaterule
+      def create_rule(source:, dest:, aggregation:)
+        cmd 'TS.CREATERULE', key_for(source), key_for(dest), Aggregation.parse(aggregation).to_a
+      end
+
+      # Delete an existing compaction rule.
+      #
+      # @param source [String, TimeSeries] the source series (or key) to remove the rule from
+      # @param dest [String, TimeSeries] the destination series (or key) the rule applies to
+      #
+      # @return [String] the string "OK"
+      # @raise [Redis::CommandError] if the compaction rule does not exist
+      def delete_rule(source:, dest:)
+        cmd 'TS.DELETERULE', key_for(source), key_for(dest)
+      end
+
+      # Delete all data and remove a time series from Redis.
+      #
+      # @param key [String] the key to remove
+      # @return [1] if the series existed
+      # @return [0] if the series did not exist
+      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))
-            # multiple timestamp => value pairs
-            value.each do |timestamp, nested_value|
-              timestamp = timestamp.ts_msec if timestamp.is_a? Time
-              memo << [key, timestamp, nested_value]
-            end
-          elsif value.is_a? Array
-            # single [timestamp, value]
-            key = key.ts_msec if key.is_a? Time
-            memo << [key, value]
-          else
-            # single value, no timestamp
-            memo << [key, '*', value]
-          end
+          memo << parse_madd_values(key, value)
           memo
         end.then do |args|
-          puts "DEBUG: TS.MADD #{args.join(' ')}" if ENV['DEBUG']
-          redis.call('TS.MADD', args.flatten).each_with_index.map do |result, idx|
+          cmd('TS.MADD', args).each_with_index.map do |result, idx|
             result.is_a?(Redis::CommandError) ? result : Sample.new(result, args[idx][2])
           end
         end
       end
 
-      def redis
-        @redis ||= Redis.current
+      # Search for a time series matching the provided filters. Refer to the {Filters} documentation
+      # for more details on how to filter.
+      #
+      # @example Using a filter string
+      #   Redis::TimeSeries.query_index('foo=bar')
+      #   #=> [#<Redis::TimeSeries:0x00007ff00e222788 @key="ts3", @redis=#<Redis...>>]
+      # @example Using the .where alias with hash DSL
+      #   Redis::TimeSeries.where(foo: 'bar')
+      #   #=> [#<Redis::TimeSeries:0x00007ff00e2a1d30 @key="ts3", @redis=#<Redis...>>]
+      #
+      # @param filter_value [Hash, String] a set of filters to query with
+      # @return [Array<TimeSeries>] an array of series that matched the given filters
+      #
+      # @see Filters
+      # @see https://oss.redislabs.com/redistimeseries/commands/#tsqueryindex
+      # @see https://oss.redislabs.com/redistimeseries/commands/#filtering
+      def query_index(filter_value)
+        filters = Filters.new(filter_value)
+        filters.validate!
+        cmd('TS.QUERYINDEX', filters.to_a).map { |key| new(key) }
+      end
+      alias where query_index
+
+      private
+
+      def key_for(series_or_string)
+        series_or_string.is_a?(self) ? series_or_string.key : series_or_string.to_s
       end
 
-      def redis=(client)
-        @redis = redis
+      def parse_madd_values(key, raw)
+        if raw.is_a?(Hash) || (raw.is_a?(Array) && raw.first.is_a?(Array))
+          # 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]
+        else
+          # single value, no timestamp
+          [key, '*', raw]
+        end
       end
     end
 
-    attr_reader :key, :labels, :redis, :retention, :uncompressed
+    # @return [String] the Redis key this time series is stored in
+    attr_reader :key
 
-    def initialize(key, options = {})
+    # @param key [String] the Redis key to store the time series in
+    # @param redis [Redis] an optional Redis client
+    def initialize(key, redis: self.class.redis)
       @key = key
-      # TODO: read labels from redis if not loaded in memory
-      @labels = options[:labels] || []
-      @redis = options[:redis] || self.class.redis
-      @retention = options[:retention]
-      @uncompressed = options[:uncompressed] || false
+      @redis = redis
     end
 
-    def add(value, timestamp = '*')
-      timestamp = timestamp.ts_msec if timestamp.is_a? Time
-      ts = cmd 'TS.ADD', key, timestamp, value
+    # Add a value to the series.
+    #
+    # @param value [Numeric] the value to add
+    # @param timestamp [Time, Numeric] the +Time+, or integer timestamp in milliseconds, to add the value
+    # @param uncompressed [Boolean] if true, stores data in an uncompressed format
+    #
+    # @return [Sample] the value that was added
+    # @raise [Redis::CommandError] if the value being added is older than the latest timestamp in the series
+    def add(value, timestamp = '*', uncompressed: nil)
+      ts = cmd 'TS.ADD', key, timestamp, value, ('UNCOMPRESSED' if uncompressed)
       Sample.new(ts, value)
     end
 
-    def create
-      args = [key]
-      args << ['RETENTION', retention] if retention
-      args << 'UNCOMPRESSED' if uncompressed
-      args << ['LABELS', labels.to_a] if labels.any?
-      cmd 'TS.CREATE', args.flatten
+    # Issues a TS.CREATE command for the current series.
+    # You should use class method {Redis::TimeSeries.create} instead.
+    # @api private
+    def create(retention: nil, uncompressed: nil, labels: nil)
+      cmd 'TS.CREATE', key,
+          (['RETENTION', retention] if retention),
+          ('UNCOMPRESSED' if uncompressed),
+          (['LABELS', labels.to_a] if labels&.any?)
       self
     end
 
-    def decrby(value = 1, timestamp = nil)
-      args = [key, value]
-      args << timestamp if timestamp
-      cmd 'TS.DECRBY', args
+    # Create a compaction rule for this series.
+    #
+    # @param dest [String, TimeSeries] the destination series (or key) to aggregate the data
+    # @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 [String] the string "OK"
+    # @raise [Redis::TimeSeries::AggregationError] if the given aggregation params are invalid
+    # @raise [Redis::CommandError] if the compaction rule cannot be applied to either series
+    #
+    # @see TimeSeries.create_rule
+    def create_rule(dest:, aggregation:)
+      self.class.create_rule(source: self, dest: dest, aggregation: aggregation)
+    end
+
+    # Delete an existing compaction rule.
+    #
+    # @param dest [String, TimeSeries] the destination series (or key) the rule applies to
+    #
+    # @return [String] the string "OK"
+    # @raise [Redis::CommandError] if the compaction rule does not exist
+    #
+    # @see TimeSeries.delete_rule
+    def delete_rule(dest:)
+      self.class.delete_rule(source: self, dest: dest)
+    end
+
+    # Decrement the current value of the series.
+    #
+    # @param value [Integer] the amount to decrement by
+    # @param timestamp [Time, Integer] the Time or integer millisecond timestamp to save the new value at
+    # @param uncompressed [Boolean] if true, stores data in an uncompressed format
+    #
+    # @return [Integer] the timestamp the value was stored at
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsincrbytsdecrby
+    def decrby(value = 1, timestamp = nil, uncompressed: nil)
+      cmd 'TS.DECRBY', key, value, (timestamp if timestamp), ('UNCOMPRESSED' if uncompressed)
     end
     alias decrement decrby
 
+
+    # Delete all data and remove this time series from Redis.
+    #
+    # @return [1] if the series existed
+    # @return [0] if the series did not exist
     def destroy
       redis.del key
     end
 
+    # Get the most recent sample for this series.
+    #
+    # @return [Sample] the most recent sample for this series
+    # @return [nil] if there are no samples in the series
+    #
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsget
     def get
       cmd('TS.GET', key).then do |timestamp, value|
         return unless value
@@ -84,31 +236,46 @@ class Redis
       end
     end
 
-    def incrby(value = 1, timestamp = nil)
-      args = [key, value]
-      args << timestamp if timestamp
-      cmd 'TS.INCRBY', args
+    # Increment the current value of the series.
+    #
+    # @param value [Integer] the amount to increment by
+    # @param timestamp [Time, Integer] the Time or integer millisecond timestamp to save the new value at
+    # @param uncompressed [Boolean] if true, stores data in an uncompressed format
+    #
+    # @return [Integer] the timestamp the value was stored at
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsincrbytsdecrby
+    def incrby(value = 1, timestamp = nil, uncompressed: nil)
+      cmd 'TS.INCRBY', key, value, (timestamp if timestamp), ('UNCOMPRESSED' if uncompressed)
     end
     alias increment incrby
 
-    # TODO: extract Info module, with methods for each property
+    # Get information about the series.
+    # Note that all properties of {Info} are also available on the series itself
+    # via delegation.
+    #
+    # @return [Info] an info object about the current series
+    #
+    # @see Info
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsinfo
     def info
-      cmd('TS.INFO', key).each_slice(2).reduce({}) do |h, (key, value)|
-        h[key.gsub(/(.)([A-Z])/,'\1_\2').downcase] = value
-        h
-      end
+      Info.parse series: self, data: cmd('TS.INFO', key)
     end
+    def_delegators :info, *Info.members - [:series] + %i[count length size source]
 
+    # Assign labels to the series using +TS.ALTER+
+    #
+    # @param val [Hash] a hash of label-value pairs
+    # @return [Hash] the assigned labels
+    #
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsalter
     def labels=(val)
-      @labels = val
-      cmd 'TS.ALTER', key, 'LABELS', labels.to_a.flatten
+      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|
-          ts = ts.ts_msec if ts.is_a? Time
           [key, ts, val]
         end.flatten
       elsif values.one? && values.first.is_a?(Array)
@@ -128,30 +295,50 @@ class Redis
       cmd 'TS.MADD', args
     end
 
-    def range(range, count: nil, agg: nil)
-      if range.is_a? Hash
-        args = range.fetch(:from), range.fetch(:to)
-      elsif range.is_a? Range
-        args = range.min, range.max
-      end
-      args.map! { |ts| (ts.to_f * 1000).to_i }
-      args.append('COUNT', count) if count
-      args.append('AGGREGATION', agg) if agg
-      cmd('TS.RANGE', key, args).map do |ts, val|
-        Sample.new(ts, val)
+    # Get a range of values from the series
+    #
+    # @param range [Hash, Range] a time range, or hash of +from+ and +to+ values
+    # @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 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.fetch(:to)
       end
+      cmd('TS.RANGE',
+          key,
+          range.min,
+          range.max,
+          (['COUNT', count] if count),
+          Aggregation.parse(aggregation)&.to_a
+         ).map { |ts, val| Sample.new(ts, val) }
     end
 
+    # Set data retention time for the series using +TS.ALTER+
+    #
+    # @param val [Integer] the number of milliseconds data should be retained. +0+ means retain forever.
+    # @return [Integer] the retention value of the series
+    #
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsalter
     def retention=(val)
-      @retention = val.to_i
+      # TODO: this should also accept an ActiveSupport::Duration
       cmd 'TS.ALTER', key, 'RETENTION', val.to_i
     end
 
-    private
-
-    def cmd(name, *args)
-      puts "DEBUG: #{name} #{args.join(' ')}" if ENV['DEBUG']
-      redis.call name, *args
+    # Compare series based on Redis key and configured client.
+    # @return [Boolean] whether the two TimeSeries objects refer to the same series
+    def ==(other)
+      return false unless other.is_a?(self.class)
+      key == other.key && redis == other.redis
     end
   end
 end

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