redis-time-series 0.1.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2bb0c44197c39258529e093bb34aa0a04576743c4f3d07016f607f9d84cd15e
-  data.tar.gz: 95ce400fcbbdeff4adcd326dd3927f535410be3180526c34068926c1908ac447
+  metadata.gz: 60ddc8ba631c4016031490a9eb8c3e8659d6b38d3f21e3798a253ec3f63b2815
+  data.tar.gz: 7993209c75f9f23ed0fae6f918020f2a7a793575e6636e57c1bc225db3f3a63d
 SHA512:
-  metadata.gz: ea5a10679174714e5f7ad63fe00f093c0d65c2c5954d11c19ea5a6b52a1660d897cb63e8ba6f6c037ca7f31e5281857f90a9fe2485dc0b401d37f281bd82ec70
-  data.tar.gz: c3cfb8e9632e9876b7cb39888fe89aab86e8becda9b64f3c6c2f4f78e4c58f59595255111820e89914c46a1a29d0a25c8c50f80c6b4311bb60e5b5141137c400
+  metadata.gz: 1bd033ed2dfef155ba923ebee94089e41f507dcb8fcb63711a56585703d1603c32ff86b99067641b8a248587925d2bf489affd79822118e5fb42b05dbcf1c374
+  data.tar.gz: 553ffbea629efff4b1b436faf7542f35204cd9a0f47c2cf28dcd3ecc0261bd399eb19ac57a56985fc3fbeaef0e4b2e24786483bc385e06928fedcbad4f6709d0

data/.github/workflows/rspec.yml

@@ -0,0 +1,43 @@
+name: RSpec
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+  schedule:
+    - cron:  '0 0 * * *'
+
+jobs:
+  spec:
+    runs-on: ubuntu-latest
+    services:
+      redis:
+        image: redislabs/redistimeseries:latest
+        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
+    - 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
+    - name: Run specs
+      run: bundle exec 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/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## Unreleased
+
+## 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
+
+## 0.2.0
+* Converted `#info` to a struct instead of a hash.
+* Added methods on time series for getting info attributes.
+
+## 0.1.1
+Fix setting labels on `TS.CREATE` and `TS.ALTER`
+
+## 0.1.0
+
+Basic functionality. Includes commands:
+* `TS.CREATE`
+* `TS.ALTER`
+* `TS.ADD`
+* `TS.MADD`
+* `TS.INCRBY`
+* `TS.DECRBY`
+* `TS.RANGE`
+* `TS.GET`
+* `TS.INFO`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    redis-time-series (0.1.0)
+    redis-time-series (0.5.0)
       redis (~> 4.0)
 
 GEM
@@ -16,15 +16,17 @@ GEM
     coderay (1.1.3)
     concurrent-ruby (1.1.6)
     diff-lcs (1.3)
+    docile (1.3.2)
     i18n (1.8.3)
       concurrent-ruby (~> 1.0)
+    json (2.3.1)
     method_source (1.0.0)
     minitest (5.14.1)
     pry (0.13.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
     rake (13.0.1)
-    redis (4.1.4)
+    redis (4.2.1)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)
       rspec-expectations (~> 3.9.0)
@@ -38,6 +40,11 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
     rspec-support (3.9.3)
+    simplecov (0.17.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
     thread_safe (0.3.6)
     tzinfo (1.2.7)
       thread_safe (~> 0.1)
@@ -53,6 +60,7 @@ DEPENDENCIES
   rake (~> 13.0)
   redis-time-series!
   rspec (~> 3.0)
+  simplecov (< 0.18)
 
 BUNDLED WITH
    1.17.2

data/README.md

@@ -1,3 +1,9 @@
+[![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
 
 A Ruby adapter for the [RedisTimeSeries module](https://oss.redislabs.com/redistimeseries).
@@ -10,6 +16,7 @@ docker run -p 6379:6379 -it --rm redislabs/redistimeseries
 
 **TL;DR**
 ```ruby
+require 'redis-time-series'
 ts = Redis::TimeSeries.new('foo')
 ts.add 1234
 => #<Redis::TimeSeries::Sample:0x00007f8c0d2561d8 @time=2020-06-25 23:23:04 -0700, @value=0.1234e4>
@@ -48,7 +55,7 @@ Create a series (issues `TS.CREATE` command) and return a Redis::TimeSeries obje
 ```ruby
 ts = Redis::TimeSeries.create(
   'your_ts_key',
-  labels: ['foo', 'bar'],
+  labels: { foo: 'bar' },
   retention: 600,
   uncompressed: false,
   redis: Redis.new(url: ENV['REDIS_URL']) # defaults to Redis.current
@@ -69,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
@@ -85,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
@@ -116,31 +131,202 @@ 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=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=
+  [#<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
+ts.labels
+=> {"foo"=>"bar"}
+ts.total_samples
+=> 3
+
+# Total samples also available as #count, #length, and #size
+ts.count
+=> 3
+ts.length
+=> 3
+ts.size
+=> 3
 ```
+Find series matching specific label(s)
+```ruby
+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.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`
-* `TS.QUERYINDEX`
-* Compaction rules
-* Filters
 * Probably a bunch more stuff
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup`. You need the `docker` daemon installed and running. This script will:
+* Install gem dependencies
+* Pull the latest `redislabs/redistimeseries` image
+* Start a Redis server on port 6379
+* Seed three time series with some sample data
+* Attach to the running server and print logs to `STDOUT`
+
+With the above script running, or after starting a server manually, you can run `bin/console` to interact with it. The three series are named `ts1`, `ts2`, and `ts3`, and are available as instance variables in the console.
+
+If you want to see the commands being executed, run the console with `DEBUG=true bin/console` and it will output the raw command strings as they're executed.
+```ruby
+[1] pry(main)> @ts1.increment
+DEBUG: TS.INCRBY ts1 1
+=> 1593159795467
+[2] pry(main)> @ts1.get
+DEBUG: TS.GET ts1
+=> #<Redis::TimeSeries::Sample:0x00007f8e1a190cf8 @time=2020-06-26 01:23:15 -0700, @value=0.4e1>
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Use `rake spec` to run the test suite.
 
 ## Contributing
 

data/bin/console

@@ -3,17 +3,12 @@
 require 'bundler/setup'
 require 'active_support/core_ext/numeric/time'
 require 'pry'
+require 'redis'
 require 'redis-time-series'
 
-Redis.current.flushall
-
-@ts1 = Redis::TimeSeries.create('foo')
-@ts2 = Redis::TimeSeries.create('bar')
-@ts3 = Redis::TimeSeries.create('baz')
-
+@ts1 = Redis::TimeSeries.new('ts1')
+@ts2 = Redis::TimeSeries.new('ts2')
+@ts3 = Redis::TimeSeries.new('ts3')
 @series = [@ts1, @ts2, @ts3]
-@series.each do |ts|
-  3.times { ts.increment }
-end
 
 Pry.start

data/bin/setup

@@ -1,8 +1,31 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
+#!/usr/bin/env ruby
 
-bundle install
+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}" }
 
-# Do any other automated setup that you need to do here
+require 'bundler/setup'
+require 'active_support/core_ext/numeric/time'
+require 'redis'
+require 'redis-time-series'
+
+Redis.current.flushall
+ts1 = Redis::TimeSeries.create('ts1')
+ts2 = Redis::TimeSeries.create('ts2')
+ts3 = Redis::TimeSeries.create('ts3')
+
+ts1.add 12, 6.minutes.ago
+ts1.add 34, 4.minutes.ago
+ts1.add 56, 2.minutes.ago
+
+10.times { ts2.increment; sleep 0.01 }
+
+ts3.labels = { foo: 'bar' }
+ts3.add 1
+sleep 0.01
+ts3.incrby 2
+sleep 0.01
+ts3.decrement
+
+system "docker logs -f #{container_id}"