redi_search 0.1.0

data/.travis.yml

@@ -0,0 +1,23 @@
+---
+env:
+  global:
+    - CC_TEST_REPORTER_ID=fec34310f03fd2cc767a85fa23d5102f3dca67b9cc967a48d9940027731394e8
+sudo: false
+language: ruby
+cache: bundler
+rvm: 2.6.3
+before_install: gem install bundler -v 1.17.3
+services: docker
+before_script:
+  - 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
+before_install:
+  - docker run -d -p 6379:6379 redislabs/redisearch:latest --protected-mode no --loadmodule /usr/lib/redis/modules/redisearch.so
+after_script:
+  - if [[ "$TRAVIS_TEST_RESULT" == 0 ]]; then ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT; fi
+script: bundle exec $COMMAND
+matrix:
+  include:
+    - env: COMMAND='rake test'
+    - env: COMMAND=rubocop

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at npezza93@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+gemspec
+
+gem "faker"
+gem "minitest", "~> 5.0"
+gem "pry"
+gem "pry-rails"
+gem "rails", "~> 6.0.0.rc1"
+gem "rubocop"
+gem "rubocop-performance"
+gem "simplecov"
+gem "sqlite3"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Nick Pezza
+
+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,220 @@
+# RediSearch
+
+[![Build Status](https://travis-ci.com/npezza93/redi_search.svg?branch=master)](https://travis-ci.com/npezza93/redi_search)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/c6437acac5684de2549d/test_coverage)](https://codeclimate.com/github/npezza93/redi_search/test_coverage)
+[![Maintainability](https://api.codeclimate.com/v1/badges/c6437acac5684de2549d/maintainability)](https://codeclimate.com/github/npezza93/redi_search/maintainability)
+
+A simple, but powerful Ruby wrapper around RediSearch,
+a search engine on top of Redis.
+
+## Installation
+
+Firstly, Redis and RediSearch need to be installed.
+
+You can download Redis from https://redis.io/download, and check out installation instructions [here](https://github.com/antirez/redis#installing-redis). Alternatively, on macOS or Linux you can install via Homebrew.
+
+To install RediSearch:
+1. `git clone https://github.com/RedisLabsModules/RediSearch.git`
+1. `cd RediSearch`
+1. `mkdir build`
+1. `cd build`
+1. `cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo`
+1. `make`
+1. `redis-server --loadmodule ./redisearch.so or load the module in your redis.conf`
+
+You can also checkout [here](https://oss.redislabs.com/redisearch/Quick_Start.html) for more detailed installation instructions. If you already have a redis-server running you can also update your redis.conf file to always load the redisearch module. (On macOS the redis.conf file can be found `/usr/local/etc/redis.conf`)
+
+
+After Redis and RediSearch are up and running, add this line to your application's Gemfile:
+
+```ruby
+gem 'redi_search'
+```
+
+And then execute:
+```bash
+❯ bundle
+````
+
+Or install it yourself as:
+```bash
+❯ gem install redi_search
+```
+
+and require it:
+```ruby
+require 'redi_search'
+```
+
+## Usage
+
+### Configuration
+```ruby
+RediSearch.configure do |config|
+  config.redis_config = {
+    host: "127.0.0.1",
+    port: "6379"
+  }
+end
+```
+
+### Index
+
+All actions revolve around indexes. To instantiate one:
+```ruby
+RediSearch::Index.new(name_of_index, schema)
+```
+The name is a string identifying the index and the schema is the argument is a hash that defines all the fields in an index. Each field can be one of four types: geo, numeric, tag, or text.
+
+#### Text field options
+- *weight* (default: 1.0)
+  - Declares the importance of this field when calculating result accuracy. This is a multiplication factor.
+  - Ex: `{ name: { text: { weight: 2 } } }`
+- *phonetic*
+  - Will perform phonetic matching on field in searches by default. The obligatory {matcher} argument specifies the phonetic algorithm and language used. The following matchers are supported:
+    - dm:en - Double Metaphone for English
+    - dm:fr - Double Metaphone for French
+    - dm:pt - Double Metaphone for Portuguese
+    - dm:es - Double Metaphone for Spanish
+  - Ex: `{ name: { text: { phonetic: 'dm:en' } } }`
+- *sortable* (default: false)
+  -  Allows the user to later sort the results by the value of this field (this adds memory overhead so do not declare it on large text fields).
+  - Ex: `{ name: { text: { sortable: true } } }`
+- *no_index* (default: false)
+  - Field will not be indexed. This is useful in conjunction with `sortable`, to create fields whose update using PARTIAL will not cause full reindexing of the document. If a field has `no_index` and doesn't have `sortable`, it will just be ignored by the index.
+  - Ex: `{ name: { text: { no_index: true } } }`
+- *no_stem* (default: false)
+  - Disable stemming when indexing its values. This may be ideal for things like proper names.
+  - Ex: `{ name: { text: { no_stem: true } } }`
+
+#### Numeric field options
+- *sortable* (default: false)
+  -  Allows the user to later sort the results by the value of this field (this adds memory overhead so do not declare it on large text fields).
+  - Ex: `{ id: { numeric: { sortable: true } } }`
+- *no_index* (default: false)
+  - Field will not be indexed. This is useful in conjunction with `sortable`, to create fields whose update using PARTIAL will not cause full reindexing of the document. If a field has `no_index` and doesn't have `sortable`, it will just be ignored by the index.
+  - Ex: `{ id: { numeric: { no_index: true } } }`
+
+#### Tag field options
+- *sortable* (default: false)
+  -  Allows the user to later sort the results by the value of this field (this adds memory overhead so do not declare it on large text fields).
+  - Ex: `{ tag: { tag: { sortable: true } } }`
+- *no_index* (default: false)
+  - Field will not be indexed. This is useful in conjunction with `sortable`, to create fields whose update using PARTIAL will not cause full reindexing of the document. If a field has `no_index` and doesn't have `sortable`, it will just be ignored by the index.
+  - Ex: `{ tag: { tag: { no_index: true } } }`
+- *separator* (default: ",")
+  - Indicates how the text contained in the field is to be split into individual tags. The default is ,. The value must be a single character.
+  - Ex: `{ tag: { tag: { separator: ',' } } }`
+
+#### Geo field options
+- *sortable* (default: false)
+  -  Allows the user to later sort the results by the value of this field (this adds memory overhead so do not declare it on large text fields).
+  - Ex: `{ place: { geo: { sortable: true } } }`
+- *no_index* (default: false)
+  - Field will not be indexed. This is useful in conjunction with `sortable`, to create fields whose update using PARTIAL will not cause full reindexing of the document. If a field has `no_index` and doesn't have `sortable`, it will just be ignored by the index.
+  - Ex: `{ place: { geo: { no_index: true } } }`
+
+Some of the commands that are available on an index are as follows:
+- *create*
+  - creates the index in the Redis instance, returns a boolean. Has an accompanying bang method that will raise an exception upon failure.
+- *drop*
+  - drops the index from the Redis instance, returns a boolean. Has an accompanying bang method that will raise an exception upon failure.
+- *exist?*
+  - Returns a boolean signifying indexes existence.
+- *info*  
+  - Returns a hash with all the information for the index
+- *fields*
+  - Returns an array of field names in the index
+- *add*
+  - Takes an object as the first argument and a second argument that is a score (a value between 0.0 and 1.0). The object passed must respond to all the fields in the schema. Has an accompanying bang method that will raise an exception upon failure.
+- *add_multiple!*
+  - Takes an array of objects that respond to all the fields in the schema. This provides a more performant way to add multiple documents to the index.
+
+### Searching
+
+Searching is initiated off an `RediSearch::Index` object.
+```ruby
+main ❯ index = RediSearch::Index.new("user_idx", name: { text: { phonetic: "dm:en" } })
+main ❯ index.search("john")
+  RediSearch (1.1ms)  FT.SEARCH user_idx `john`
+=> [#<RediSearch::Document:0x00007f862e241b78 first: "Gene", last: "Volkman", document_id: "10039">,
+#<RediSearch::Document:0x00007f862e2417b8 first: "Jeannie", last: "Ledner", document_id: "9998">]
+```
+- Simple phrase query - hello AND world
+```ruby
+index.search("hello").and("world")
+```
+- Exact phrase query - hello FOLLOWED BY world
+```ruby
+index.search("hello world")
+```
+- Union: documents containing either hello OR world
+```ruby
+index.search("hello").or("world")
+```
+- Not: documents containing hello but not world
+```ruby
+index.search("hello").and.not("world")
+```
+
+All terms support a few options that can be applied.
+
+- Prefix Queries: match all terms starting with a prefix
+```ruby
+index.search("hel", prefix: true)
+index.search("hello worl", prefix: true)
+index.search("hel", prefix: true).and("worl", prefix: true)
+index.search("hello").and.not("worl", prefix: true)
+```
+
+- Optional terms with higher priority to ones containing more matches
+```ruby
+index.search("foo").and("bar", optional: true).and("baz", optional: true)
+```
+
+- Fuzzy matches are performed based on Levenshtein distance (LD). The maximum Levenshtein distance supported is 3.
+```ruby
+index.search("zuchini", fuzziness: 1)
+```
+
+- Complex intersections and unions
+```ruby
+# Intersection of unions
+index.search(index.search("hello").or("halo")).and(index.search("world").or("werld"))
+# Negation of union
+index.search("hello").and.not(index.search("world").or("werld"))
+# Union inside phrase
+index.search("hello").and(index.search("world").or("werld"))
+```
+
+### Rails Integration
+
+Integration with Rails is on by default! All you have to do is add the following to the model you want to search:
+```ruby
+class User < ApplicationRecord
+  redi_search schema: {
+    first: { text: { phonetic: "dm:en" } },
+    last: { text: { phonetic: "dm:en" } }
+  }
+end
+```
+
+This will automatically add `User.search` and `User.reindex` methods. You can also use `User.redi_search_index` to get the `RediSearch::Index` instance. `User.reindex` will first `drop` the index if it exists, create the index with the given schema, and then add all the records to the index.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. You can also start a rails console if you `cd` into `test/dummy`.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, execute `bin/publish (major|minor|patch)` which will update the version number in `version.rb`, create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/npezza93/redi_search. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the RediSearch project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/npezza93/redi_search/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "redi_search"
+
+require "pry"
+Pry.start

data/bin/publish

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "pathname"
+require "fileutils"
+require_relative "../lib/redi_search/version"
+
+# path to your application root.
+APP_ROOT = Pathname.new File.expand_path("..", __dir__)
+MASTER_CHECK = <<~MASTER_CHECK
+  if [ $(git symbolic-ref --short -q HEAD) != 'master' ];
+    then exit 1;
+  fi
+MASTER_CHECK
+VERSION_TYPES = %w(major minor patch).freeze
+
+def system!(*args)
+  system(*args) || abort("\n== Command #{args} failed ==")
+end
+
+abort("\n== Version Type incorrect ==") unless VERSION_TYPES.include?(ARGV[0])
+
+abort("\n== Not on master") unless system(MASTER_CHECK)
+
+current_version = RediSearch::VERSION.split(".").map(&:to_i)
+
+case ARGV[0]
+when "major"
+  current_version[0] += 1
+  current_version[1] = 0
+  current_version[2] = 0
+when "minor"
+  current_version[1] += 1
+  current_version[2] = 0
+when "patch"
+  current_version[2] += 1
+end
+
+FileUtils.chdir APP_ROOT do
+  contents = <<~FILE
+    # frozen_string_literal: true
+
+    module RediSearch
+      VERSION = "#{current_version.join('.')}"
+    end
+  FILE
+
+  puts "== Updating version to #{current_version.join('.')} =="
+  File.write("lib/redi_search/version.rb", contents)
+
+  system! "git add lib/redi_search/version.rb"
+
+  puts "== Committing updated files =="
+  system! "git commit -m 'Version bump to #{current_version.join('.')}'"
+
+  puts "== Tagging release =="
+  system! "bundle exec rake release"
+end

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/bin/test

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$: << File.expand_path("../test", __dir__)
+
+require "bundler/setup"
+require "rails/plugin/test"

data/lib/redi_search/client.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "redis"
+
+module RediSearch
+  class Client
+    class Response < SimpleDelegator
+      def initialize(response)
+        @response = response
+
+        super(response)
+      end
+
+      def ok?
+        if response.is_a? String
+          response == "OK"
+        elsif response.is_a? Array
+          response.all? { |pipeline_response| pipeline_response == "OK" }
+        else
+          response
+        end
+      end
+
+      private
+
+      attr_reader :response
+    end
+
+    def initialize(redis_config)
+      @redis = Redis.new(redis_config)
+    end
+
+    def call!(command, *params)
+      instrument(command.downcase, query: [command, params]) do
+        send_command(command, *params)
+      end
+    end
+
+    def pipelined
+      Response.new(redis.pipelined do
+        instrument("pipeline", query: ["begin pipeline"])
+        yield
+        instrument("pipeline", query: ["finish pipeline"])
+      end)
+    end
+
+    private
+
+    attr_reader :redis
+
+    def send_command(command, *params)
+      Response.new(redis.call("FT.#{command}", *params))
+    end
+
+    def instrument(action, payload)
+      block =
+        if block_given?
+          Proc.new
+        else
+          proc {}
+        end
+
+      ActiveSupport::Notifications.instrument(
+        "#{action}.redi_search", { name: "RediSearch" }.merge(payload), &block
+      )
+    end
+  end
+end

data/lib/redi_search/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "redi_search/client"
+
+module RediSearch
+  class Configuration
+    attr_writer :redis_config
+
+    def client
+      @client ||= Client.new(redis_config)
+    end
+
+    def redis_config
+      @redis_config ||= { host: "127.0.0.1", port: "6379" }
+    end
+  end
+end

data/lib/redi_search/document/converter.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RediSearch
+  class Document
+    class Converter
+      def initialize(index, record)
+        @index = index
+        @record = record
+      end
+
+      def document
+        Document.new(
+          index,
+          record.id,
+          index.schema.fields.map do |field|
+            [field.to_s, record.public_send(field)]
+          end.to_h
+        )
+      end
+
+      private
+
+      attr_reader :index, :record
+    end
+  end
+end

data/lib/redi_search/document.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module RediSearch
+  class Document
+    class << self
+      def get(index, document_id)
+        response = RediSearch.client.call!("GET", index.name, document_id)
+
+        return if response.blank?
+
+        new(index, document_id, Hash[*response])
+      end
+
+      def mget(index, *document_ids)
+        document_ids.zip(
+          RediSearch.client.call!("MGET", index.name, *document_ids)
+        ).map do |document|
+          next if document[1].blank?
+
+          new(index, document[0], Hash[*document[1]])
+        end.compact
+      end
+    end
+
+    attr_reader :document_id
+
+    def initialize(index, document_id, fields)
+      @index = index
+      @document_id = document_id
+      @to_a = []
+
+      schema_fields.each do |field|
+        @to_a.push([field, fields[field]])
+        instance_variable_set(:"@#{field}", fields[field])
+        define_singleton_method field do
+          fields[field]
+        end
+      end
+    end
+
+    def del
+      client.call!("DEL", index.name, document_id).ok?
+    end
+
+    #:nocov:
+    def pretty_print(printer) # rubocop:disable Metrics/MethodLength
+      printer.object_address_group(self) do
+        printer.seplist(
+          schema_fields.append("document_id"), proc { printer.text "," }
+        ) do |field_name|
+          printer.breakable " "
+          printer.group(1) do
+            printer.text field_name
+            printer.text ":"
+            printer.breakable
+            printer.pp public_send(field_name)
+          end
+        end
+      end
+    end
+    #:nocov:
+
+    def schema_fields
+      @schema_fields ||= index.schema.fields.map(&:to_s)
+    end
+
+    def to_a
+      @to_a.flatten
+    end
+
+    private
+
+    attr_reader :index
+
+    def client
+      RediSearch.client
+    end
+  end
+end

data/lib/redi_search/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module RediSearch
+  class Error < StandardError
+  end
+end