redi_set 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d8c7c9190ff4f3fa2008d58feb0293fc5f6edb094875919a0f7fa97e6a811994
+  data.tar.gz: 35bcd5d99938b3638caa6760a971e4e093639bcca4f98b22c609597b8acbea76
+SHA512:
+  metadata.gz: a481586ab8389c7fc09eed24d58f1db163a87e60b890cafeab477e6c2719d5d19070df7fd9f03c756490055ae798e649c6df7196404b0fc5ad987797e6a849a8
+  data.tar.gz: 8dde81c7e5f25f77a37ae25df6e406ee0e076a8dbbf6d069136aa64beb20db1ef07320ccfc8046e2a1ec9fad50fccaa71323ec26bcbf2f03bb64b0060e71e9f4

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2020 Eric Mueller
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,23 @@
+## What Is It?
+
+RediSet is a redis-backed library that makes it easy to find members within a population
+satisfying sets of attribute constraints. Given information about a large population of
+cats for example, we could quickly find the set of cats that are male, calico, short-hair,
+and live in Oregon.
+
+## But Why?
+
+This problem is easy to solve for most situations - if you just need to generate a list,
+you can process a csv with a very simple script or a perl one-liner. If you only have to
+handle a few thousand cats, any database will do the trick - table-scans aren't *that*
+costly.
+
+But if you have millions of records, they receive frequent updates (because some of your
+attributes are mutable), records are added and removed on a regular basis, and you need to
+perform a continuous stream of varied requests, you may find that your queries aren't scaling
+well - a *set* querying engine is one straightforward solution to that problem.
+
+With hash-backed sets, we can perform intersections very quickly - if we simply model every
+attribute as multiple sets (the set of male cats and the set of female cats, for example),
+we can easily construct lists of records that match complex constraints with pure set union
+and intersection operations. And Redis has that data structure ready to go!

data/lib/redi_set.rb

@@ -0,0 +1,31 @@
+module RediSet
+  def self.prefix
+    configuration.prefix
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  class Configuration
+    attr_accessor :prefix
+
+    def initialize
+      @prefix = "rs"
+    end
+  end
+end
+
+require "redis"
+require "hiredis"
+require "redis/connection/hiredis"
+
+require_relative "redi_set/attribute"
+require_relative "redi_set/quality"
+require_relative "redi_set/constraint"
+require_relative "redi_set/query"
+require_relative "redi_set/client"

data/lib/redi_set/attribute.rb

@@ -0,0 +1,9 @@
+module RediSet
+  class Attribute
+    attr_reader :name
+
+    def initialize(name:)
+      @name = name
+    end
+  end
+end

data/lib/redi_set/client.rb

@@ -0,0 +1,35 @@
+module RediSet
+  class Client
+    attr_reader :redis
+
+    def initialize(redis: nil, redis_config: nil)
+      if redis
+        @redis = redis
+      elsif redis_config
+        @redis = Redis.new(redis_config)
+      else
+        fail ArgumentError, "redis or redis_config must be supplied to the RediSet::Client"
+      end
+    end
+
+    def match(constraint_hash)
+      RediSet::Query.from_hash(constraint_hash).execute(@redis)
+    end
+
+    def set_all!(attribute_name, quality_name, ids)
+      attribute = Attribute.new(name: attribute_name)
+      quality = Quality.new(attribute: attribute, name: quality_name)
+      quality.set_all!(@redis, ids)
+    end
+
+    # details here is a three-layer hash: attribute_name => quality_name => boolean.
+    # only specified attribute/qualities will be updated.
+    def set_details!(id, details)
+      possessed_qualities, lacked_qualities = Quality.collect_from_details(details)
+      @redis.multi do
+        possessed_qualities.each { |q| @redis.sadd(q.key, id) }
+        lacked_qualities.each { |q| @redis.srem(q.key, id) }
+      end
+    end
+  end
+end

data/lib/redi_set/constraint.rb

@@ -0,0 +1,46 @@
+require "securerandom"
+
+module RediSet
+  class Constraint
+    UNION_EXPIRATION_PERIOD = 60 # seconds
+
+    def initialize(qualities:)
+      @qualities = qualities
+
+      if qualities.length < 1
+        raise ArgumentError, "A constraint must have at least one quality"
+      elsif qualities.map(&:attribute).uniq.length != 1
+        raise ArgumentError, "All qualities in a constraint must have matching attributes"
+      end
+    end
+
+    attr_reader :qualities
+
+    def attribute
+      qualities.first.attribute
+    end
+
+    def requires_union?
+      qualities.length > 1
+    end
+
+    def intersection_key
+      if requires_union?
+        union_key
+      else
+        qualities.first.key
+      end
+    end
+
+    def store_union(redis)
+      redis.sunionstore union_key, qualities.map(&:key)
+      redis.expire(union_key, UNION_EXPIRATION_PERIOD)
+    end
+
+    private
+
+    def union_key
+      @_key ||= "#{RediSet.prefix}.union:#{SecureRandom.uuid}"
+    end
+  end
+end

data/lib/redi_set/quality.rb

@@ -0,0 +1,41 @@
+module RediSet
+  class Quality
+    attr_reader :attribute, :name
+
+    # parse a layered hash like "attribute_name => { quality_name => possessed? }" into a pair
+    # of Arrays of quality objects, one full of qualities they should possess, the other full
+    # of qualities they should not possess.
+    def self.collect_from_details(details)
+      qheld = []
+      qlacked = []
+      details.each_pair do |attribute_name, attribute_details|
+        attribute = Attribute.new(name: attribute_name)
+        attribute_details.each_pair do |quality_name, is_held|
+          quality = Quality.new(attribute: attribute, name: quality_name)
+          if is_held
+            qheld << quality
+          else
+            qlacked << quality
+          end
+        end
+      end
+      [qheld, qlacked]
+    end
+
+    def initialize(attribute:, name:)
+      @attribute = attribute
+      @name = name
+    end
+
+    def key
+      @_key ||= "#{RediSet.prefix}.attr:#{attribute.name}:#{name}"
+    end
+
+    def set_all!(redis, ids)
+      redis.multi do
+        redis.del(key)
+        redis.sadd(key, ids)
+      end
+    end
+  end
+end

data/lib/redi_set/query.rb

@@ -0,0 +1,25 @@
+module RediSet
+  class Query
+    attr_reader :constraints
+
+    def self.from_hash(constraint_hash)
+      constraints = constraint_hash.map do |key, val|
+        attribute = Attribute.new(name: key)
+        qualities = Array(val).map { |v| Quality.new(attribute: attribute, name: v) }
+        Constraint.new(qualities: qualities)
+      end
+      RediSet::Query.new(constraints)
+    end
+
+    def initialize(constraints)
+      @constraints = constraints
+    end
+
+    def execute(redis)
+      redis.multi do
+        constraints.select(&:requires_union?).each { |c| c.store_union(redis) }
+        redis.sinter(constraints.map(&:intersection_key))
+      end.last
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: redi_set
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eric Mueller
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-10-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: hiredis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  A redis-backed library that makes it easy to find members of a population that
+  satisfy a set of attribute constraints using redis set operations.
+email: nevinera@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/redi_set.rb
+- lib/redi_set/attribute.rb
+- lib/redi_set/client.rb
+- lib/redi_set/constraint.rb
+- lib/redi_set/quality.rb
+- lib/redi_set/query.rb
+homepage: https://github.com/nevinera/redi_set
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
+summary: A set-based redis query engine
+test_files: []