redi_search 1.0.4 → 3.0.0

data/Appraisals

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-appraise "rails-6" do
-  gem "rails", "6.0.0.rc1"
+appraise "activerecord-52" do
+  gem "activerecord", "< 6.0", ">= 5.2"
 end
 
-appraise "rails-52" do
-  gem "rails", "< 6.0", ">= 5.2"
+appraise "activerecord-51" do
+  gem "activerecord", "< 5.2", ">= 5.1"
 end
 
-appraise "rails-51" do
-  gem "rails", "< 5.2", ">= 5.1"
+appraise "activerecord-61" do
+  gem "activerecord", "6.1.0.rc1"
 end

data/Gemfile

@@ -2,18 +2,18 @@
 
 source "https://rubygems.org"
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 gemspec
 
+gem "appraisal", "~> 2.2"
 gem "faker"
 gem "mocha"
 gem "pry"
-gem "pry-rails"
 gem "rubocop"
+gem "rubocop-minitest"
 gem "rubocop-performance"
-gem "rubocop-rails"
 gem "simplecov"
 gem "sqlite3"
 
-gem "rails", "6.0.0.rc1"
+gem "activerecord", "~> 6.0.0"

data/README.md

@@ -6,8 +6,7 @@
 
 # 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)
+![Build Status](https://github.com/npezza93/redi_search/workflows/tests/badge.svg)
 [![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
@@ -24,11 +23,13 @@ macOS or Linux you can install via Homebrew.
 
 To install RediSearch check out,
 [https://oss.redislabs.com/redisearch/Quick_Start.html](https://oss.redislabs.com/redisearch/Quick_Start.html).
-Once you have RediSearch built, you can update your redis.conf file to always
-load the redisearch module with `loadmodule /path/to/redisearch.so`. (On macOS
-the redis.conf file can be found `/usr/local/etc/redis.conf`)
+Once you have RediSearch built, if you are not using Docker, you can update your
+redis.conf file to always load the RediSearch module with
+`loadmodule /path/to/redisearch.so`. (On macOS the redis.conf file can be found
+at `/usr/local/etc/redis.conf`)
 
-After Redis and RediSearch are up and running, add this line to your Gemfile:
+After Redis and RediSearch are up and running, add the following line to your
+Gemfile:
 
 ```ruby
 gem 'redi_search'
@@ -51,7 +52,7 @@ require 'redi_search'
 
 Once the gem is installed and required you'll need to configure it with your
 Redis configuration. If you're on Rails, this should go in an initializer
-(`config/initializers/redi_search.rb`)
+(`config/initializers/redi_search.rb`).
 
 ```ruby
 RediSearch.configure do |config|
@@ -74,7 +75,7 @@ end
 
 ## Preface
 RediSearch revolves around a search index, so lets start with
-defining what a search index is. According to [Switype](https://swiftype.com):
+defining what a search index is. According to [Swiftype](https://swiftype.com):
 > A search index is a body of structured data that a search engine refers to
 > when looking for results that are relevant to a specific query. Indexes are a
 > critical piece of any search system, since they must be tailored to the
@@ -242,40 +243,35 @@ With no options: `{ place: :geo }`
 
 ## Document
 
-A `Document` is the Ruby representation of a RediSearch document.
+A `Document` is the Ruby representation of a Redis hash.
 
-You can fetch a `Document` using `.get` or `mget` class methods.
-- `get(index, document_id)` fetches a single document in an `Index` for a given
-`document_id`.
-- `mget(index, *document_ids)` fetches a collection of `Document`s
-in an `Index` for the given `document_ids`.
+You can fetch a `Document` using `.get` class methods.
+- `get(index, document_id)` fetches a single `Document` in an `Index` for a
+given `document_id`.
 
 You can also make a `Document` instance using the
 `.for_object(index, record, serializer: nil, only: [])` class method. It takes
-an `Index` instance and a ruby object. That object must respond to all the
-fields specified in the indexes schema or pass a serializer class that accepts
-the object and responds to all the fields specified in the indexes schema.
-`only` accepts an array of fields from the schema and limits the fields that are
-passed to the `Document`.
+an `Index` instance and a Ruby object. That object must respond to all the
+fields specified in the `Index`'s `Schema` or pass a serializer class that
+accepts the object and responds to all the fields specified in the `Index`'s
+`Schema`. `only` accepts an array of fields from the schema and limits the
+fields that are passed to the `Document`.
 
 Once you have an instance of a `Document`, it responds to all the fields
-specified in the indexes schema as methods and `document_id`. `document_id` is
-automatically prepended with the indexes names unless it already is to ensure
-uniqueness. We prepend the index name because if you have two documents with the
-same id in different indexes we don't want the documents to override each other.
-There is also a `#document_id_without_index` method which removes the prepended
-index name.
-
-Finally there is a `#del` method that will remove the document from the index.
-It optionally accepts a `delete_document` named argument that signifies whether
-the document should be completely removed from the Redis instance vs just the
-index.
+specified in the `Index`'s `Schema` as methods and `document_id`. `document_id`
+is automatically prepended with the `Index`'s names unless it already is to
+ensure uniqueness. We prepend the `Index` name because if you have two
+`Document`s with the same id in different `Index`s we don't want the `Document`s
+to override each other. There is also a `#document_id_without_index` method
+which removes the prepended index name.
 
+Finally there is a `#del` method that will remove the `Document` from the
+`Index`.
 
 ## Index
 
-To initialize an index, pass the name of the index as a string or symbol and the
-schema.
+To initialize an `Index`, pass the name of the `Index` as a string or symbol
+and the `Schema`.
 
 ```ruby
 RediSearch::Index.new(name_of_index, schema)
@@ -291,7 +287,7 @@ RediSearch::Index.new(name_of_index, schema)
         - For efficiency, RediSearch encodes indexes differently if they are
           created with less than 32 text fields. This option forces RediSearch
           to encode indexes as if there were more than 32 text fields, which
-          allows you to add additional fields (beyond 32) using `alter`.
+          allows you to add additional fields (beyond 32) using `add_field`.
       - `no_offsets: #{true || false}`
         - If set, we do not store term offsets for documents (saves memory, does
           not allow exact searches or highlighting). Implies `no_highlight`.
@@ -312,50 +308,39 @@ RediSearch::Index.new(name_of_index, schema)
         - If set, we avoid saving the term frequencies in the index. This saves
           memory but does not allow sorting based on the frequencies of a given
           term within the document.
-- `drop`
-  - Drops the index from the Redis instance, returns a boolean. Has an
+- `drop(keep_docs: false)`
+  - Drops the `Index` from the Redis instance, returns a boolean. Has an
     accompanying bang method that will raise an exception upon failure. Will
-    return `false` if the index has already been dropped.
+    return `false` if the `Index` has already been dropped. Takes an option
+    keyword arg, `keep_docs`, that will by default remove all the document
+    hashes in Redis.
 - `exist?`
-  - Returns a boolean signifying index existence.
+  - Returns a boolean signifying `Index` existence.
 - `info`
-  - Returns a struct object with all the information about the index.
+  - Returns a struct object with all the information about the `Index`.
 - `fields`
-  - Returns an array of the field names in the index.
-- `add(document, score: 1.0, replace: {}, language: nil, no_save: false)`
-  - Takes a `Document` object and options. Has an
+  - Returns an array of the field names in the `Index`.
+- `add(document)`
+  - Takes a `Document` object. Has an
     accompanying bang method that will raise an exception upon failure.
-    - `score` -> The document's rank, a value between 0.0 and 1.0
-    - `language` -> Use a stemmer for the supplied language during indexing.
-    - `no_save` -> Don't save the actual document in the database and only index it.
-    - `replace` -> Accepts a boolean or a hash. If a truthy value is passed, we
-      will do an UPSERT style insertion - and delete an older version of the
-      document if it exists.
-    - `replace: { partial: true }` -> Allows you to not have to specify all
-      fields for reindexing. Fields not given to the command will be loaded from
-      the current version of the document.
-- `add_multiple!(documents, score: 1.0, replace: {}, language: nil, no_save: false)`
+- `add_multiple(documents)`
   - Takes an array of `Document` objects. This provides a more performant way to
-    add multiple documents to the index. Accepts the same options as `add`.
-- `del(document, delete_document: false)`
-  - Removes a document from the index. `delete_document` signifies whether the
-    document should be completely removed from the Redis instance vs just the
-    index.
+    add multiple documents to the `Index`. Accepts the same options as `add`.
+- `del(document)`
+  - Removes a `Document` from the `Index`.
 - `document_count`
-  - Returns the number of documents in the index
-- `alter(field_name, schema)`
-  - Adds a new field to the index. Ex: `index.alter(:first_name, text: { phonetic: "dm:en" })`
-- `reindex(documents, recreate: false, **options)`
-   - If `recreate` is `true` the index will be dropped and recreated
-   - `options` accepts the same options as `add`
+  - Returns the number of `Document`s in the `Index`
+- `add_field(field_name, schema)`
+  - Adds a new field to the `Index`. Ex: `index.add_field(:first_name, text: { phonetic: "dm:en" })`
+- `reindex(documents, recreate: false)`
+   - If `recreate` is `true` the `Index` will be dropped and recreated
 
 
 ## Searching
 
 Searching is initiated off a `RediSearch::Index` instance with clauses that can
 be chained together. When searching, an array of `Document`s is returned
-which has public reader methods for all the schema fields and a `document_id`
-method which returns the id of the document prefixed with the index name.
+which has public reader methods for all the schema fields.
 
 ```ruby
 main ❯ index = RediSearch::Index.new("user_idx", name: { text: { phonetic: "dm:en" } })
@@ -440,15 +425,15 @@ index.search.where(number: -Float::INFINITY..0)
   phrase terms. (i.e the slop for exact phrases is 0)
 - `in_order`
   - Usually used in conjunction with `slop`. We make sure the query terms appear
-    in the same order in the document as in the query, regardless of the offsets
-    between them.
+    in the same order in the `Document` as in the query, regardless of the
+    offsets between them.
 - `no_content`
-  - Only return the document ids and not the content. This is useful if
-    RediSearch is being used on a Rails model where the document attributes
-    don't matter and it's being converted into ActiveRecord objects.
+  - Only return the `Document` ids and not the content. This is useful if
+    RediSearch is being used on a Rails model where the `Document` attributes
+    don't matter and it's being converted into `ActiveRecord` objects.
 - `language(language)`
   - Stemmer to use for the supplied language during search for query expansion.
-    If querying documents in Chinese, this should be set to chinese in order to
+    If querying `Document`s in Chinese, this should be set to chinese in order to
     properly tokenize the query terms. If an unsupported language is sent, the
     command returns an error.
 - `sort_by(field, order: :asc)`
@@ -459,7 +444,7 @@ index.search.where(number: -Float::INFINITY..0)
   - Limit the results to the specified `num` at the `offset`. The default limit
     is set to `10`.
 - `count`
-  - Returns the number of documents found in the search query
+  - Returns the number of `Document`s found in the search query
 - `highlight(fields: [], opening_tag: "<b>", closing_tag: "</b>")`
   - Use this option to format occurrences of matched text. `fields` are an
     array of fields to be highlighted.
@@ -469,16 +454,14 @@ index.search.where(number: -Float::INFINITY..0)
 - `no_stop_words`
   - Do not filter stopwords from the query.
 - `with_scores`
-  - Include the relative internal score of each document. This can be used to
+  - Include the relative internal score of each `Document`. This can be used to
     merge results from multiple instances. This will add a `score` method to the
     returned `Document` instances.
 - `return(*fields)`
-  - Limit which fields from the document are returned.
+  - Limit which fields from the `Document` are returned.
 - `explain`
   - Returns the execution plan for a complex query. In the returned response,
     a + on a term is an indication of stemming.
-- `to_redis`
-  - Returns the command to be executed without executing it.
 
 
 ## Spellcheck
@@ -507,8 +490,8 @@ main ❯ index.spellcheck("jimy", distance: 2).first.suggestions
 
 ## Rails Integration
 
-Integration with Rails is super easy! Call `redi_search` with the schema keyword
-arg from inside your model. Ex:
+Integration with Rails is super easy! Call `redi_search` with the `schema`
+keyword argument from inside your model. Ex:
 
 ```ruby
 class User < ApplicationRecord
@@ -522,10 +505,9 @@ end
 This will automatically add `User.search` and `User.spellcheck`
 methods which behave the same as if you called them on an `Index` instance.
 
-`User.reindex(only: [], **options)` is also added and behaves similarly to `RediSearch::Index#reindex`. Some of the differences include:
-  - By default does an upsert for all documents added using the
-    option `replace: { partial: true }`.
-  - `Document`s do not to be passed as the first parameter. The `search_import`
+`User.reindex(recreate: false, only: [])` is also added and behaves
+similarly to `RediSearch::Index#reindex`. Some of the differences include:
+  - `Document`s do not need to be passed as the first parameter. The `search_import`
     scope is automatically called and all the records are converted
     to `Document`s.
   - Accepts an optional `only` parameter where you can specify a limited number
@@ -552,8 +534,8 @@ class UserSerializer < SimpleDelegator
 end
 ```
 
-You can create a scope on the model to eager load relationships when indexing or
-it can be used to limit the records to index.
+You can override the `search_import` scope on the model to eager load
+relationships when indexing or it can be used to limit the records to index.
 
 ```ruby
 class User < ApplicationRecord
@@ -561,7 +543,11 @@ class User < ApplicationRecord
 end
 ```
 
-The default index name for model indexes is
+When searching, by default a collection of `Document`s is returned. Calling
+`#results` on the search query will execute the search, and then look up all the
+found records in the database and return an ActiveRecord relation.
+
+The default `Index` name for model `Index`s is
 `#{model_name.plural}_#{RediSearch.env}`. The `redi_search` method takes an
 optional `index_prefix` argument which gets prepended to the index name:
 
@@ -578,15 +564,16 @@ User.redi_search_index.name
 ```
 
 When integrating RediSearch into a model, records will automatically be indexed
-after creating and updating and will be removed from the index upon destruction.
+after creating and updating and will be removed from the `Index` upon
+destruction.
 
-There are few more convenience methods that are publicly available:
+There are a few more convenience methods that are publicly available:
 - `redi_search_document`
   - Returns the record as a `RediSearch::Document` instance
 - `redi_search_delete_document`
-  - Removes the record from the index
+  - Removes the record from the `Index`
 - `redi_search_add_document`
-  - Adds the record to the index
+  - Adds the record to the `Index`
 - `redi_search_index`
   - Returns the `RediSearch::Index` instance
 
@@ -594,15 +581,15 @@ There are few more convenience methods that are publicly available:
 ## 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`.
+`rake test` to run the both unit and integration tests. To run them individually
+you can run `rake test:unit` or `rake test:integration`. You can also run
+`bin/console` for an interactive prompt that will allow you to experiment.
 
 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).
+[rubygems.org](https://rubygems.org) and GitHub.
 
 ## Contributing
 

data/Rakefile

@@ -1,12 +1,24 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
+require "rubocop/rake_task"
 require "rake/testtask"
 
-Rake::TestTask.new(:test) do |t|
+RuboCop::RakeTask.new(:rubocop) do |t|
+  t.options = ["--display-cop-names"]
+end
+
+Rake::TestTask.new("test:unit") do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/unit/**/*_test.rb"]
+end
+
+Rake::TestTask.new("test:integration") do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.test_files = FileList["test/integration/**/*_test.rb"]
 end
 
-task default: :test
+task test: [:default]
+task default: ["test:integration", "test:unit", :rubocop]

data/bin/console

@@ -4,5 +4,34 @@
 require "bundler/setup"
 require "redi_search"
 
+require "faker"
 require "pry"
+require "active_support/logger"
+require "active_record"
+
+ActiveSupport::LogSubscriber.logger = ActiveSupport::Logger.new(STDOUT)
+
+ActiveRecord::Base.establish_connection adapter: "sqlite3", database: ":memory:"
+
+ActiveRecord::Migration.create_table :users do |t|
+  t.string :first
+  t.string :last
+end
+
+class User < ActiveRecord::Base
+  redi_search schema: {
+    first: { text: { phonetic: "dm:en" } },
+    last: { text: { phonetic: "dm:en" } }
+  }
+end
+
+def seed_users(count = 10_000)
+  User.insert_all(
+    Array.new(count).map do
+      { first: Faker::Name.first_name, last: Faker::Name.last_name }
+    end
+  )
+  User.reindex
+end
+
 Pry.start

data/gemfiles/{rails_51.gemfile → activerecord_51.gemfile}

@@ -2,16 +2,15 @@
 
 source "https://rubygems.org"
 
+gem "appraisal", "~> 2.2"
 gem "faker"
-gem "minitest", "~> 5.0"
 gem "mocha"
 gem "pry"
-gem "pry-rails"
 gem "rubocop"
+gem "rubocop-minitest"
 gem "rubocop-performance"
-gem "rubocop-rails"
 gem "simplecov"
 gem "sqlite3"
-gem "rails", "< 5.2", ">= 5.1"
+gem "activerecord", "< 5.2", ">= 5.1"
 
 gemspec path: "../"

data/gemfiles/{rails_52.gemfile → activerecord_52.gemfile}

@@ -2,16 +2,15 @@
 
 source "https://rubygems.org"
 
+gem "appraisal", "~> 2.2"
 gem "faker"
-gem "minitest", "~> 5.0"
 gem "mocha"
 gem "pry"
-gem "pry-rails"
 gem "rubocop"
+gem "rubocop-minitest"
 gem "rubocop-performance"
-gem "rubocop-rails"
 gem "simplecov"
 gem "sqlite3"
-gem "rails", "< 6.0", ">= 5.2"
+gem "activerecord", "< 6.0", ">= 5.2"
 
 gemspec path: "../"