plain_search 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d135d34007cb8f01bbdbffc6604b9b8072da3f9d
+  data.tar.gz: c40f5ef7ecd3213c0cfdf71ecc681f7ef9ca1b82
+SHA512:
+  metadata.gz: cf154c6bc924dc477692edf5991917e4b0e6c765271ac8f5120cbeb5c27d6748f1cd9165daf476e63130d5add4509c62396a01abb8b6010846278a5d9f923fbe
+  data.tar.gz: 00e710e1e19548da9f711b0cb5b6c2c25334078b9d119a7ec31634fc6678475b87d64fbd2e01a8b505c142f6ea1a98eb75b353e92c3866c5cd32fed4bc7a8d01

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2015 Andreas Baumgart (https://baumgart.software)
+
+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,135 @@
+PlainSearch
+===========
+
+PlainSearch is a dead-simple, scored search plugin for single ActiveRecord 
+models. Suited for small projects with little needs for scalability 
+and a reserved attitude towards technical debt (i.e. ElasticSearch, Solr, ...).
+
+Quick Start
+-----------
+
+### Setup
+
+Add the Gem to your Gemfile:
+
+    gem 'plain_search'
+
+Run `bundle install` to install it. 
+
+You'll need a table for caching the search terms. Run the generator for
+a new migration:
+
+    rails g migration CreateSearchTerms
+    
+Put this into the migration file: 
+
+    class CreateSearchTerms < ActiveRecord::Migration
+        def change
+            create_table :search_terms do |t|
+                t.string :term, index: true
+                t.string :source, index: true
+                t.belongs_to :findable, polymorphic: true
+            end
+        end
+    end
+
+Apply the changes by running `rake db:migrate`.
+
+At the moment the Gem doesn't provide the AR model for search terms (feel free 
+to add it - pull requests appreciated). 
+ 
+So you'll have to add it to you model. Create `app/model/search_term.rb` with
+this content: 
+
+    class SearchTerm < ActiveRecord::Base
+      belongs_to :findable, polymorphic: true
+    end
+
+Having, for instance, a model `Employee` which has the attributes `first_name`,
+`last_name`, `profession` and `address`, you can enable ranked searches like so:
+
+    class Employee < ActiveRecord::Base
+        searchable_by id: 100, first_name: 10, last_name: 10, profession: 5, address: 1
+        # ...
+    end
+    
+`searchable_by` receives a hash as only argument. Its keys determine the 
+attributes to search. The hash's values determine the value contributed to the 
+rank for a single match. In short: The higher the value, the higher the rank. 
+See #Ranking for details.   
+
+### Performing searches
+
+Now, with all the setup done, performing a search is pretty straight-forward: 
+
+    matches = Employee.search('susi sorglos 33602 hauptstrasse developer')
+    
+`matches` contains a list of `Employee`s, ordered by the search score, which is
+also available as an attribute (e.q. `matches[0].score`).
+
+### Rebuilding search terms
+
+In the background, whenever you create or update a model on which 
+`searchable_by` was called, the searchable fields' contents will be cached in the 
+`search_terms` table. This means pre-existent records won't appear in the 
+search results because they have never hit the respective post-save callback. 
+You'll have to rebuild the cache for this models manually using 
+`#rebuild_search_terms_for_all` like so: 
+
+    Employee.rebuild_search_terms_for_all
+
+### Performing updates without caching search terms
+
+Let's say you have a scenario which performs a lot of updates to a specific 
+model. Every insertion or update would result in `SearchTerm`s being build for
+the respective record. This can be very time consuming (keep in mind that
+PlainSearch is not a high performance beast, but a mere solution for 
+prototyping). 
+ 
+To circumvent this you can call the insertions/updates inside a block passed
+to `#without_search_term_updates`. Which simply suppresses the after_save 
+callback which normally builds SearchTerms.
+ 
+An example: 
+
+    Employee.without_search_term_updates do 
+     Employee.update_all({some_non_searchable_attribute: 42})
+    end
+ 
+Therefore changes to searchable attributes within won't be reflected in the search 
+results. So you should make sure that you either rebuild the search terms 
+afterwards (e.q. using ActiveJob) or make sure no searchable attributes have 
+been touched in the operation. 
+
+Alternatively you could set `Model#auto_update_search_terms` to `true`/`false`, 
+which is basically what `#without_search_term_updates` does, but in a less 
+error-prone manner.  
+
+### Search term delimiter
+
+Values of searchable attributes are split into search terms using a regular
+expression. This is `/[^\w\u00C0-\u00ff]/` by default. You can adjust it
+to fit your specific needs: 
+
+    class Employee < ActiveRecord::Base
+        searchable_by # ...
+        search_terms_delimiter = /[\-.]/
+        # ...
+    end
+
+Ranking
+-------
+
+Plain search facilitates a very simple ranking algorithm. 
+Every attribute considered for search has a score assigned to it. This is the
+score of a single match. The total score of a search result is the sum of the
+score of all matches.
+
+Here's an example: If we had an `Employee` with `first_name` being "Susi" and 
+her `profession` being "Web developer", then (in the scenario above), a query 
+for "susi web" would result in a total score of 15 for this record. That is 10 
+for the matching first name and 5 for the matching profession. 
+
+License
+-------
+See [MIT-LICENSE](MIT-LICENSE)

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'PlainSearch'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/lib/plain_search.rb

@@ -0,0 +1,6 @@
+require 'plain_search/concern'
+require 'plain_search/railtie'
+
+module PlainSearch
+
+end

data/lib/plain_search/concern.rb

@@ -0,0 +1,186 @@
+module PlainSearch
+
+  extend ActiveSupport::Concern
+
+  included do
+
+    def clear_search_terms_for(attributes)
+      search_terms.where(source: attributes).delete_all
+    end
+
+    def changed_searchable_attributes
+      self.class.searchable_attributes.select do |attribute_name|
+        if has_attribute? attribute_name
+          attribute_changed? attribute_name
+        else
+          true # not all attributes map to DB columns and support *_changed?
+        end
+      end
+    end
+
+    def rebuild_search_terms
+      self.class.transaction do
+        clear_search_terms_for(self.class.searchable_attributes)
+        create_search_terms_for(self.class.searchable_attributes)
+      end
+    end
+
+    def create_search_terms_for(attributes)
+      self.class.transaction do
+        Array.wrap(attributes).each do |attr_name|
+          attr_value = send(attr_name)
+          self.class.tokenize_search_terms(attr_value).each do |term|
+            SearchTerm.create!(findable: self, term: term, source: attr_name)
+          end
+        end
+      end
+    end
+
+  end
+
+  class_methods do
+
+    def auto_update_search_terms?
+      !!auto_update_search_terms
+    end
+
+    def searchable?
+      searchable_attributes.present? and searchable_attributes.any?
+    end
+
+    def without_search_term_updates
+      orig_value = self.auto_update_search_terms
+      begin
+        self.auto_update_search_terms = false
+        yield if block_given?
+      ensure
+        self.auto_update_search_terms = orig_value
+      end
+    end
+
+    def searchable_by(*attributes)
+
+      has_many :search_terms, as: :findable
+
+      cattr_accessor :searchable_attributes
+      cattr_accessor :searchable_attribute_scores
+
+      cattr_accessor :auto_update_search_terms
+      self.auto_update_search_terms = true
+
+      cattr_accessor :search_terms_delimiter
+
+      # Add latin-1 umlauts to word characters.
+      # Add more if you must.
+      self.search_terms_delimiter = /[^\w\u00C0-\u00ff]/
+
+      delegate :searchable?, to: :class
+      delegate :auto_update_search_terms, to: :class
+      delegate :auto_update_search_terms?, to: :class
+
+      if attributes.size == 1 and attributes[0].is_a? Hash
+        # searchable_by attr1: 5, attr2: 1, ...
+        self.searchable_attribute_scores = attributes[0]
+        self.searchable_attributes = attributes[0].keys
+      else
+        # searchable_by :attr1, :attr2, ...
+        self.searchable_attribute_scores = nil
+        self.searchable_attributes = attributes
+      end
+
+      after_save do
+        if searchable? and auto_update_search_terms?
+          attribs = changed_searchable_attributes
+          clear_search_terms_for(attribs)
+          create_search_terms_for(attribs)
+        end
+      end
+
+    end
+
+    def tokenize_search_terms(value)
+      value.to_s.gsub(search_terms_delimiter, ' ').gsub(/\s+/, ' ').split(' ')
+    end
+
+    def rebuild_search_terms_for_all
+      self.transaction do
+        SearchTerm.where("findable_type = '#{self.name}'").delete_all
+        all.each do |record|
+          record.create_search_terms_for(self.searchable_attributes)
+        end
+      end
+    end
+
+    def search(query)
+
+      return none if searchable_attributes.empty?
+
+      terms = tokenize_search_terms(query)
+      return none if terms.empty?
+
+      if score_search?
+        perform_scored_search(terms)
+      else
+        perform_unscored_search(terms)
+      end
+
+    end
+
+    def score_search?
+      not searchable_attribute_scores.nil?
+    end
+
+    private
+
+    def search_conditions_for_terms(terms)
+      quoted_terms = terms.collect do |t|
+        ActiveRecord::Base.connection.quote("#{t}%")
+      end
+      quoted_terms.collect do |quoted_term|
+        "#{SearchTerm.table_name}.term LIKE #{quoted_term}"
+      end
+    end
+
+    def perform_scored_search(terms)
+      conditions = search_conditions_for_terms(terms)
+
+      score_statement = searchable_attributes.collect do |attr_name|
+        "WHEN search_terms.source = '#{attr_name}' then #{searchable_attribute_scores[attr_name]}"
+      end.join("\n           ")
+
+      find_by_sql <<-SQL
+        SELECT SUM(e1.match_score) AS score, e1.*
+        FROM (
+          SELECT
+           CASE
+           #{score_statement}
+           ELSE 0
+           END AS match_score,
+           #{table_name}.*
+          FROM #{table_name}
+          JOIN #{SearchTerm.table_name}
+            ON #{SearchTerm.table_name}.findable_id = #{table_name}.id
+            AND #{SearchTerm.table_name}.findable_type = '#{self.name}'
+          WHERE #{conditions.join(' OR ')}
+          ) AS e1
+        GROUP BY e1.id
+        ORDER BY score DESC
+      SQL
+    end
+
+    def perform_unscored_search(terms)
+      conditions = search_conditions_for_terms(terms)
+      find_by_sql <<-SQL
+        SELECT #{table_name}.*, COUNT(#{SearchTerm.table_name}.id) as hits
+        FROM #{table_name}
+        JOIN #{SearchTerm.table_name}
+          ON #{SearchTerm.table_name}.findable_id = #{table_name}.id
+          AND #{SearchTerm.table_name}.findable_type = '#{self.name}'
+        WHERE #{conditions.join(' OR ')}
+        GROUP BY #{table_name}.id
+        ORDER BY hits DESC
+      SQL
+    end
+  end
+
+end

data/lib/plain_search/railtie.rb

@@ -0,0 +1,13 @@
+module PlainSearch
+  class Railtie < Rails::Railtie
+
+    initializer 'plain_search.extend_active_record_base' do
+      ActiveRecord::Base.send(:include, PlainSearch)
+    end
+
+    rake_tasks do
+      load "tasks/plain_search.rake"
+    end
+
+  end
+end

data/lib/plain_search/version.rb

@@ -0,0 +1,3 @@
+module PlainSearch
+  VERSION = "0.1.0"
+end

data/lib/tasks/plain_search.rake

@@ -0,0 +1,19 @@
+namespace :plain_search do
+
+  desc "Clear and rebuild search terms for a given model class"
+  task rebuild: :environment do
+
+    class_name = ENV['CLASS']
+
+    abort('Usage: rake plain_search:rebuild_terms CLASS=MySearchableModel') if class_name.blank?
+
+    klass = Object.const_get(class_name)
+
+    raise "Plain Search is not enabled on model #{class_name}" unless klass.searchable?
+
+    puts "Rebuilding search terms for model #{class_name}..."
+    klass.rebuild_search_terms_for_all
+    puts "Done."
+  end
+
+end

data/test/dummy/README.rdoc

@@ -0,0 +1,28 @@
+== README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...
+
+
+Please feel free to use a different markup language if you do not plan to run
+<tt>rake doc:app</tt>.