redis-time-series 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d699daec01bb891952501de6a51cc4b966be74a0f8585030bafb4f6a908b36e
-  data.tar.gz: dfa027d344c4d5485b0a22a33edd67973c2a60cb60dbbaa1a57101ccce8833fc
+  metadata.gz: 4648678522434687a6e278490c7a308c64f6460394b8ebde16b2ce2daa9e92ad
+  data.tar.gz: e2f48fb1c8efebb3b4d6e4c47d1d86137a10ac8a54735c94b3bdb35ef6396651
 SHA512:
-  metadata.gz: acadcad9c6919e810f0e100bfe20b60055507e2efa98d0853fca6c15a252f99b65c722c71acc99d37d8d9f72964d91f862c9604fb96458ca3faaddce9f841752
-  data.tar.gz: 489415e8247d8cffefcf13e4e70c82cde752170c4416bc0973495c5d38b1d27d2b554cdd62db8729c9c71b125cb4848aa5a1efd81b998aa5f6e5683c13be8ccc
+  metadata.gz: 269a787d8d2a2a467a52e915ab717bc5b20eb28cacc55eb5dfc9ce3909a7d83cdd4e15b19afc92612d19fa551c6ba793df76ceef03d8bb8bdb16b6dc0253d2cc
+  data.tar.gz: c5d845052ca8f2a518fb3a20a82a8d8aa35128cb824f54d2531a949767e90f8c7979ede07ba1bd56ae30a825edb9f6be90e52ca404a14199bfd13484026d8d40

data/.github/workflows/rspec.yml

@@ -11,18 +11,39 @@ on:
 jobs:
   spec:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        image_version: ['latest', 'edge']
+        ruby_version: ['2.6', '2.7']
     services:
       redis:
-        image: redislabs/redistimeseries:latest
+        image: redislabs/redistimeseries:${{ matrix.image_version }}
         ports:
           - 6379:6379/tcp
+    env:
+      CC_TEST_REPORTER_ID: ${{ secrets.CC_TEST_REPORTER_ID }}
+      GIT_COMMIT_SHA: ${{ github.sha }}
+      GIT_BRANCH: ${{ github.head_ref }}
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 2.6
+        ruby-version: ${{ matrix.ruby_version }}
+    - name: Set up CodeClimate
+      run: |
+        curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+        chmod +x ./cc-test-reporter
+        ./cc-test-reporter before-build
     - name: Install dependencies
-      run: bundle install
+      run: |
+        bundle install
+        bundle exec appraisal install
     - name: Run specs
-      run: bundle exec rake spec
+      run: bundle exec appraisal rake spec
+    - name: Upload coverage report
+      run: ./cc-test-reporter after-build -t simplecov coverage/.resultset.json
+    - uses: actions/upload-artifact@v2
+      with:
+        name: coverage
+        path: coverage/

data/.gitignore

@@ -6,6 +6,7 @@
 /pkg/
 /spec/reports/
 /tmp/
+Gemfile.lock
 
 # rspec failure tracking
 .rspec_status

data/Appraisals

@@ -0,0 +1,7 @@
+appraise 'redis 3' do
+  gem 'redis', '~> 3.3'
+end
+
+appraise 'redis 4' do
+  gem 'redis', '~> 4.0'
+end

data/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## Unreleased
 
+## 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)
+* Add support for endless ranges to TS.RANGE (#50)
+* Cast label values to integers in Info struct (#49)
+* Build against edge upstream in addition to latest stable (#48)
+
+## 0.5.2
+* Add chunk_type to info struct (#47)
+
+## 0.5.1
+* Update Info struct for RTS 1.4 compatibility (#45)
+
+## 0.5.0
+* Fix aggregations for TS.RANGE command (#34)
+* Extract client handling into Client module (#32)
+* Add `uncompressed` param to TS.ADD, TS.INCRBY, TS.DECRBY (#35)
+* Add `Redis::TimeSeries::Rule` object (#38)
+* Add [YARD documentation](https://rubydoc.info/gems/redis-time-series) (#40)
+
+## 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/README.md

@@ -1,5 +1,8 @@
 [![RSpec](https://github.com/dzunk/redis-time-series/workflows/RSpec/badge.svg)](https://github.com/dzunk/redis-time-series/actions?query=workflow%3ARSpec+branch%3Amaster)
 [![Gem Version](https://badge.fury.io/rb/redis-time-series.svg)](https://badge.fury.io/rb/redis-time-series)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-brightgreen)](https://rubydoc.info/gems/redis-time-series)
+[![Maintainability](https://api.codeclimate.com/v1/badges/19a5925c20318508b4a4/maintainability)](https://codeclimate.com/github/dzunk/redis-time-series/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/19a5925c20318508b4a4/test_coverage)](https://codeclimate.com/github/dzunk/redis-time-series/test_coverage)
 
 # RedisTimeSeries
 
@@ -73,6 +76,10 @@ Add a single value with a timestamp
 ```ruby
 ts.add 1234, 3.minutes.ago # Used ActiveSupport here, but any Time object works fine
 => #<Redis::TimeSeries::Sample:0x00007fa6ce05f3f8 @time=2020-06-25 23:39:54 -0700, @value=0.1234e4>
+
+# Optionally store data uncompressed
+ts.add 5678, uncompressed: true
+=> #<Redis::TimeSeries::Sample:0x00007f93f43cdf68 @time=2020-07-18 23:15:29 -0700, @value=0.5678e4>
 ```
 Add multiple values with timestamps
 ```ruby
@@ -89,6 +96,10 @@ ts.increment # alias of incrby
 => 1593154255069
 ts.decrement # alias of decrby
 => 1593154257344
+
+# Optionally store data uncompressed
+ts.incrby 4, uncompressed: true
+=> 1595139299769
 ```
 ```ruby
 ts.get
@@ -120,31 +131,53 @@ ts.get
 ```
 Get a range of values
 ```ruby
-ts.range 10.minutes.ago..Time.current # Time range as an argument
+# Time range as an argument
+ts.range(10.minutes.ago..Time.current)
 => [#<Redis::TimeSeries::Sample:0x00007fa25f13fc28 @time=2020-06-25 23:50:51 -0700, @value=0.57e2>,
- #<Redis::TimeSeries::Sample:0x00007fa25f13db58 @time=2020-06-25 23:50:55 -0700, @value=0.58e2>,
- #<Redis::TimeSeries::Sample:0x00007fa25f13d900 @time=2020-06-25 23:50:57 -0700, @value=0.57e2>,
- #<Redis::TimeSeries::Sample:0x00007fa25f13d680 @time=2020-06-25 23:51:30 -0700, @value=0.58e2>]
-ts.range from: 10.minutes.ago, to: Time.current # Time range as keyword args
+    #<Redis::TimeSeries::Sample:0x00007fa25f13db58 @time=2020-06-25 23:50:55 -0700, @value=0.58e2>,
+    #<Redis::TimeSeries::Sample:0x00007fa25f13d900 @time=2020-06-25 23:50:57 -0700, @value=0.57e2>,
+    #<Redis::TimeSeries::Sample:0x00007fa25f13d680 @time=2020-06-25 23:51:30 -0700, @value=0.58e2>]
+
+# Time range as keyword args
+ts.range(from: 10.minutes.ago, to: Time.current)
+=> [#<Redis::TimeSeries::Sample:0x00007fa25dc01f00 @time=2020-06-25 23:50:51 -0700, @value=0.57e2>,
+    #<Redis::TimeSeries::Sample:0x00007fa25dc01d20 @time=2020-06-25 23:50:55 -0700, @value=0.58e2>,
+    #<Redis::TimeSeries::Sample:0x00007fa25dc01b68 @time=2020-06-25 23:50:57 -0700, @value=0.57e2>,
+    #<Redis::TimeSeries::Sample:0x00007fa25dc019b0 @time=2020-06-25 23:51:30 -0700, @value=0.58e2>]
+
+# Limit number of results with count argument
+ts.range(10.minutes.ago..Time.current, count: 2)
 => [#<Redis::TimeSeries::Sample:0x00007fa25dc01f00 @time=2020-06-25 23:50:51 -0700, @value=0.57e2>,
- #<Redis::TimeSeries::Sample:0x00007fa25dc01d20 @time=2020-06-25 23:50:55 -0700, @value=0.58e2>,
- #<Redis::TimeSeries::Sample:0x00007fa25dc01b68 @time=2020-06-25 23:50:57 -0700, @value=0.57e2>,
- #<Redis::TimeSeries::Sample:0x00007fa25dc019b0 @time=2020-06-25 23:51:30 -0700, @value=0.58e2>]
+    #<Redis::TimeSeries::Sample:0x00007fa25dc01d20 @time=2020-06-25 23:50:55 -0700, @value=0.58e2>]
+
+# Apply aggregations to the range
+ts.range(from: 10.minutes.ago, to: Time.current, aggregation: [:avg, 10.minutes])
+=> [#<Redis::TimeSeries::Sample:0x00007fa25dc01f00 @time=2020-06-25 23:50:00 -0700, @value=0.575e2>]
 ```
 Get info about the series
 ```ruby
 ts.info
 => #<struct Redis::TimeSeries::Info
+ series=
+  #<Redis::TimeSeries:0x00007ff46da9b578 @key="ts3", @redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>>,
  total_samples=3,
- memory_usage=4184,
- first_timestamp=1594060993011,
- last_timestamp=1594060993060,
+ memory_usage=4264,
+ first_timestamp=1595187993605,
+ last_timestamp=1595187993629,
  retention_time=0,
  chunk_count=1,
  max_samples_per_chunk=256,
  labels={"foo"=>"bar"},
  source_key=nil,
- rules=[]>
+ rules=
+  [#<Redis::TimeSeries::Rule:0x00007ff46db30c68
+    @aggregation=#<Redis::TimeSeries::Aggregation:0x00007ff46db30c18 @duration=3600000, @type="avg">,
+    @destination_key="ts1",
+    @source=
+     #<Redis::TimeSeries:0x00007ff46da9b578
+      @key="ts3",
+      @redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>>>]>
+
 # Each info property is also a method on the time series object
 ts.memory_usage
 => 4208
@@ -152,6 +185,7 @@ ts.labels
 => {"foo"=>"bar"}
 ts.total_samples
 => 3
+
 # Total samples also available as #count, #length, and #size
 ts.count
 => 3
@@ -162,23 +196,113 @@ 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
+# Destintation time series needs to be created before the rule is added.
+other_ts = Redis::TimeSeries.create('other_ts')
+
+# Aggregation buckets are measured in milliseconds
+ts.create_rule(dest: other_ts, aggregation: [:count, 60000]) # 1 minute
+
+# Can provide a string key instead of a time series object
+ts.create_rule(dest: 'other_ts', aggregation: [:avg, 120000])
+
+# If you're using Rails or ActiveSupport, you can provide an
+# ActiveSupport::Duration instead of an integer
+ts.create_rule(dest: other_ts, aggregation: [:avg, 2.minutes])
+
+# 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])
+```
+Get existing compaction rules
+```ruby
+ts.rules
+=> [#<Redis::TimeSeries::Rule:0x00007ff46e91c728
+  @aggregation=#<Redis::TimeSeries::Aggregation:0x00007ff46e91c6d8 @duration=3600000, @type="avg">,
+  @destination_key="ts1",
+  @source=
+   #<Redis::TimeSeries:0x00007ff46da9b578 @key="ts3", @redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>>>]
+
+# Get properties of a rule too
+ts.rules.first.aggregation
+=> #<Redis::TimeSeries::Aggregation:0x00007ff46d146d38 @duration=3600000, @type="avg">
+ts.rules.first.destination
+=> #<Redis::TimeSeries:0x00007ff46d8a3d60 @key="ts1", @redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>>
+```
+
+Remove an existing compaction rule
+```ruby
+ts.delete_rule(dest: 'other_ts')
+ts.rules.first.delete
+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/bin/setup

@@ -3,10 +3,12 @@
 system 'bundle install'
 system 'docker pull redislabs/redistimeseries:latest'
 container_id = `docker run -p 6379:6379 -dit --rm redislabs/redistimeseries`
+at_exit { system "docker stop #{container_id}" }
 
 require 'bundler/setup'
 require 'active_support/core_ext/numeric/time'
 require 'redis'
+require 'redis-time-series'
 
 Redis.current.flushall
 ts1 = Redis::TimeSeries.create('ts1')
@@ -26,5 +28,4 @@ ts3.incrby 2
 sleep 0.01
 ts3.decrement
 
-at_exit { system "docker stop #{container_id}" }
 system "docker logs -f #{container_id}"

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,11 +1,15 @@
 require 'bigdecimal'
 require 'forwardable'
-require 'time/msec'
-require 'redis/time_series/filter'
+require 'ext/time_msec'
+
+require 'redis/time_series/client'
+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/rule'
 require 'redis/time_series/info'
 require 'redis/time_series/sample'
 require 'redis/time_series'
 
-class RedisTimeSeries
-  VERSION = '0.3.0'
-end
+class RedisTimeSeries; end

data/lib/redis/time_series.rb

@@ -1,88 +1,257 @@
 # 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.
+      # @option options [String, Symbol] :duplicate_policy
+      #   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
+      #
+      # @return [Redis::TimeSeries] the created time series
+      # @see https://oss.redislabs.com/redistimeseries/commands/#tscreate
       def create(key, **options)
-        new(key, **options).create(labels: options[:labels])
+        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 queryindex(filter_value)
-        filters = Filter.new(filter_value)
+      # 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!
-        redis.call('TS.QUERYINDEX', *filters.to_a).map { |key| new(key) }
+        cmd('TS.QUERYINDEX', filters.to_a).map { |key| new(key) }
       end
+      alias where query_index
+
+      private
 
-      def redis
-        @redis ||= Redis.current
+      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, :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
-      @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
+    # @param on_duplicate [String, Symbol] a duplication policy for conflict resolution
+    # @param chunk_size [Integer] set default chunk size, in bytes, for the time series
+    #
+    # @return [Sample] the value that was added
+    # @raise [Redis::CommandError] if the value being added is older than the latest timestamp in the series
+    #
+    # @see TimeSeries::DuplicatePolicy
+    def add(value, timestamp = '*', uncompressed: nil, on_duplicate: nil, chunk_size: nil)
+      ts = cmd 'TS.ADD',
+               key,
+               timestamp,
+               value,
+               ('UNCOMPRESSED' if uncompressed),
+               (['CHUNK_SIZE', chunk_size] if chunk_size),
+               (DuplicatePolicy.new(on_duplicate).to_a('ON_DUPLICATE') if on_duplicate)
       Sample.new(ts, value)
     end
 
-    def create(labels: nil)
-      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, duplicate_policy: nil, chunk_size: nil)
+      cmd 'TS.CREATE', key,
+          (['RETENTION', retention] if retention),
+          ('UNCOMPRESSED' if uncompressed),
+          (['CHUNK_SIZE', chunk_size] if chunk_size),
+          (DuplicatePolicy.new(duplicate_policy).to_a if duplicate_policy),
+          (['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
+    # @param chunk_size [Integer] set default chunk size, in bytes, for the time series
+    #
+    # @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, chunk_size: nil)
+      cmd 'TS.DECRBY',
+          key,
+          value,
+          (timestamp if timestamp),
+          ('UNCOMPRESSED' if uncompressed),
+          (['CHUNK_SIZE', chunk_size] if chunk_size)
     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
@@ -90,28 +259,52 @@ 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
+    # @param chunk_size [Integer] set default chunk size, in bytes, for the time series
+    #
+    # @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, chunk_size: nil)
+      cmd 'TS.INCRBY',
+          key,
+          value,
+          (timestamp if timestamp),
+          ('UNCOMPRESSED' if uncompressed),
+          (['CHUNK_SIZE', chunk_size] if chunk_size)
     end
     alias increment incrby
 
+    # 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).then(&Info.method(:parse))
+      Info.parse series: self, data: cmd('TS.INFO', key)
     end
-    def_delegators :info, *Info.members
-    %i[count length size].each { |m| def_delegator :info, :total_samples, m }
+    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)
-      cmd 'TS.ALTER', key, 'LABELS', val.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)
@@ -131,30 +324,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[: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) }
     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