elasticsearch-facetedsearch 0.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1e6625292febfa91f3b4c88c2664eab607d2edf3
+  data.tar.gz: 23929ddb68d398a41a4dc49fb55f6f8fd5d1504b
+SHA512:
+  metadata.gz: 8614e10f04da9baf552148827245a2bd93a1e66974155a844209ca97717381a2e5effa84cf3a2465c828a02357abfae6d392a6a8d9ae5a6ff38f646cc8be0dd3
+  data.tar.gz: 3e9b1ef954bb8d7931549eff70b8e81fd3520a40211524b9aea094ce630bbae197ab4079fc03257c8a56234b2cd3f05af8853922cb2331a7ed472c8eef0b8a7b

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# 0.0.4 - hotfix
+
+- Pagination was occationally missing a page due to a non-float
+
+# 0.0.3 - hotfix
+
+- Added spec due to improper merge on 0.0.2 tag
+- Fixed bug with bad hash merge on :facet_filter parameter
+
+# 0.0.2
+
+- Allow facets to keep counts regardless of filters applied
+- Updating readme to reflect this capability
+
+# 0.0.1
+
+- Initial release
+- Contains full test suite

data/README.md

@@ -0,0 +1,216 @@
+# Elasticsearch::FacetedSearch
+
+[![Code Climate](https://codeclimate.com/github/spodlecki/elasticsearch-facetedsearch/badges/gpa.svg)](https://codeclimate.com/github/spodlecki/elasticsearch-facetedsearch)
+[![Test Coverage](https://codeclimate.com/github/spodlecki/elasticsearch-facetedsearch/badges/coverage.svg)](https://codeclimate.com/github/spodlecki/elasticsearch-facetedsearch/coverage)
+[![Build Status](https://travis-ci.org/spodlecki/elasticsearch-facetedsearch.svg)](https://travis-ci.org/spodlecki/elasticsearch-facetedsearch)
+
+Quickly add faceted searching to your Rails app. This gem is opinionated as to how faceted searching works. **Filters are applied to the counts** so the counts themselves will change while different filters are applied.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'elasticsearch-facetedsearch'
+
+And then execute:
+
+    $ bundle
+
+Create `config/initializers/elasticsearch.rb`. We normally namespace our indexed like below.
+
+    ELASTICSEARCH_INDEX = [
+      Rails.env.development? && `whoami`.strip,
+      Rails.env,
+      Rails.application.class.to_s.split("::").first.downcase
+    ].reject(&:blank?).join('_')
+
+    # Optional concepts to help with indexing / connection
+    ELASTICSEARCH_MODELS = []
+    ELASTICSEARCH_SERVER = 'http://lalaland.com:9200'
+
+    Elasticsearch::Model.client = Elasticsearch::Client.new({
+      log: false,
+      host: ELASTICSEARCH_SERVER,
+      retry_on_failure: 5,
+      reload_connections: true
+    })
+
+## Dependencies
+
+- [Elasticsearch::Model](https://github.com/elastic/elasticsearch-rails/tree/master/elasticsearch-model)
+- [Rails > 3.2.8](http://rubyonrails.org/)
+- [Elasticsearch Server > 1.0.1](http://www.elastic.co)
+
+## Usage
+
+### Controller
+
+    # Good idea to prefilter the params with strong_params
+    #
+    def search
+      @search = FruitFacetsSearch.new(params)
+
+      # Fetch results
+      # @search.results
+
+      # Fetch facets
+      # @search.facets
+    end
+
+### Facet Search Class
+
+    class FruitFacetsSearch
+      include Elasticsearch::FacetedSearch::FacetBase
+
+      # ... include other facet classes (examples below) ...
+      include Elasticsearch::FacetedSearch::FacetColor
+
+      # *required
+      # The type to search for (Elasticsearch Type)
+      # Can be an Array or String
+      def type
+        'fruit'
+      end
+
+      # Use this to add a query search or something
+      # Probably best to cache the results
+      def query
+        @query ||= super
+      end
+
+      # Apply additional pre-filters
+      # If overwriting this method, ensure to call super, and ensure to cache the results
+      # => require color to be 'blue'
+      def filter_query
+        @filter_query ||= begin
+          fq = super
+          fq << { term: { color: 'blue' } }
+          fq
+        end
+      end
+
+      # Force specific limit or allow changable #s
+      #
+      def limit
+        33
+      end
+
+      # Whitelisted collection of sortable options
+      def sorts
+        [
+          {
+            label: "Relevant",
+            value: "relevant",
+            search: [
+              "_score"
+            ],
+            default: true
+          }
+        ]
+      end
+
+      # Want to always keep facet counts the same regardless of filters applied?
+      # pass true to keep counts scoped to search, & false to remove filters entirely
+      #
+      def build_facets
+        super(false)
+      end
+    end
+
+### Facet Creation Class
+
+    module Elasticsearch
+      module FacetedSearch
+        module FacetColor
+          extend ActiveSupport::Concern
+
+          included do
+            # Adds the facet to the class.facets collection
+            #
+            # Available types:
+            # => facet_multivalue
+            # => facet_multivalue_and(:ident, 'elasticsearch_field', 'Human String')
+            #     - Allows multiple values, but filters with :and execution
+            # => facet_multivalue_or(:ident, 'elasticsearch_field', 'Human String')
+            #     - Allows multiple values, but filters with :or execution
+            # => facet_exclusive_or(:ident, 'elasticsearch_field', 'Human String')
+            #     - Allows single value only
+            #
+            facet_multivalue_or(:color, 'color_field', 'Skin Color')
+          end
+
+          # *required
+          # Should we apply the filter for this facet?
+          # __Replace 'color' with the :ident value of your facet key
+          def filter_color?
+            valid_color?
+          end
+
+          # *required
+          # Returns the array of selected values
+          # __Replace 'color' with the :ident value of your facet key
+          # __You should really take this time to whitelist the values and remove any noise. Elasticsearch can be picky if you're searching a number field and pass it an alpha character
+          def color_value
+            return unless valid_color?
+            search_params[:color].split( operator_for(:color) )
+          end
+
+          # (optional)
+          # By default, Elasticsearch only returns terms that are pertaining to the specific search. If a result was filtered out, that term would not show up.
+          # Normally this isn't optimal... create this method and return an array of hashes with id and term keys.
+          #
+          # __Replace 'color' with the :ident value of your facet key
+          def color_collection
+            @color_collection ||= begin
+              Color.all.map{|x| {id: x.id, term: x.name}}
+            end
+          end
+
+          # (concept)
+          # Use these type of helper methods to validate the information given to you by users
+          #
+          def valid_color?
+            search_params[:color].present? && !!(search_params[:color] =~ /[\|[0-9]+]/)
+          end
+        end
+      end
+    end
+
+### Using Sortable
+
+The only requirement to change sort options is to apply a `:sort` http param
+
+### Pagniation
+
+Pagination is supported, but only tested with Kaminari.
+
+### HTML
+
+**Facets**
+
+    %ul
+      -@search.facets.each do |group|
+        %li.title=group.title
+        -group.items.each do |item|
+          - # Assuming you have some dynamic urls, you can use the url_for and merge in the params
+          %li=item.link_to("#{item.term} (#{item.count})", url_for(params.merge(item.params_for)))
+
+**Results**
+
+    %ul
+      -@search.results.each do |item|
+        - # item is now direct reference to the elastic search _source
+        - # item also contains item._type that displays the Elasticsearch type field
+        %li=item.id
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## TODO
+
+- Setup facet generator

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+# If you want to make this the default task
+task :default => :spec
+
+require "bundler/gem_tasks"

data/lib/elasticsearch/faceted_search.rb

@@ -0,0 +1,15 @@
+require 'active_support'
+require 'active_support/core_ext'
+require 'elasticsearch/model'
+require "elasticsearch/faceted_search/version"
+require "elasticsearch/faceted_search/pagination"
+require "elasticsearch/faceted_search/sortable"
+require "elasticsearch/faceted_search/facet_base"
+
+require "elasticsearch/faceted_search/facet_group"
+require "elasticsearch/faceted_search/facet_item"
+
+module Elasticsearch
+  module FacetedSearch
+  end
+end

data/lib/elasticsearch/faceted_search/facet_base.rb

@@ -0,0 +1,184 @@
+require 'ostruct'
+require 'elasticsearch/model'
+
+module Elasticsearch
+  module FacetedSearch
+    module FacetBase
+      include Pagination
+      include Sortable
+
+      extend ActiveSupport::Concern
+
+      included do
+        extend ClassMethods
+        attr_accessor :params
+
+        def initialize(p)
+          self.params = p
+        end
+
+        def results
+          @results ||= search['hits']['hits'].map{|x| Hashie::Mash.new(x['_source'].merge('_type' => x['_type'])) }
+        end
+
+        def facets
+          @facets ||= search['facets'].map{|key, values| FacetGroup.new(self, key, values) }
+        end
+
+        def search
+          @search ||= Elasticsearch::Model.client.search({
+                index: ELASTICSEARCH_INDEX,
+                type: type,
+                body: query
+              })
+        end
+      end
+
+      ## self <<
+      module ClassMethods
+
+        def facets
+          @facets || []
+        end
+
+        def facet(name, field, type, title)
+          @facets ||= {}
+          @facets.merge!({
+            name.to_sym => {
+              field: field,
+              type: type,
+              title: title
+            }
+          })
+        end
+
+        def facet_multivalue(name, field, title = nil)
+          facet(name, field, 'multivalue', title)
+        end
+
+        def facet_multivalue_and(name, field, title = nil)
+          facet(name, field, 'multivalue_and', title)
+        end
+
+        def facet_multivalue_or(name, field, title = nil)
+          facet(name, field, 'multivalue_or', title)
+        end
+
+        def facet_exclusive_or(name, field, title = nil)
+          facet(name, field, 'exclusive_or', title)
+        end
+      end
+      # / self
+
+      ##############
+      # Instance
+      #
+      def class_facets
+        self.class.facets.dup
+      end
+
+      def query
+        q = {
+          size: limit,
+          from: ([current_page.to_i, 1].max - 1) * limit,
+          sort: current_sort_for_search
+        }
+
+        # Filters
+        q.merge!({
+          :filter => {
+            :and => filter_query
+          }
+        }) unless filter_query.blank?
+
+        # Facets
+        q.merge!({
+          :facets => facet_query
+        }) unless facet_query.blank?
+
+        q.reject{|k,v| v.blank? }
+      end
+
+      def facet_query
+        @facet_query ||= build_facets
+      end
+
+      def filter_query
+        @filter_query ||= build_filters
+      end
+
+      def search_params
+        params
+      end
+
+    protected
+
+      def operator_mappings(i=nil)
+        FacetGroup::OPERATOR_MAPPING.fetch(i, nil)
+      end
+
+      def operator_for(key)
+        operator_mappings(
+          execution_type(
+            class_facets[key][:type]
+          )
+        )
+      end
+
+      def execution_type(type)
+        case type
+          when 'multivalue'
+            # TODO: Based off params
+          when 'multivalue_or'
+            :or
+          when 'multivalue_and'
+            :and
+          when 'exclusive_or'
+            nil
+        end
+      end
+
+      def facet_size_allowed
+        70
+      end
+
+    private
+
+      def build_facets(filter_counts=true)
+        h = {}
+        filtered_facets = filter_counts && filter_query.present? ? {facet_filter: { :and => filter_query }} : {}
+
+        class_facets.each do |k,v|
+          h.merge!({
+            k => {
+              terms: {
+                field: v[:field],
+                size: facet_size_allowed
+              }
+            }.merge(filtered_facets).reject{|k,v| v.blank?}
+          })
+        end
+
+        h
+      end
+
+      # Whitelist and filter
+      def build_filters
+        class_facets.map do |type, info|
+          if respond_to?(:"filter_#{type}?") and public_send("filter_#{type}?")
+            {
+              terms: {
+                info[:field] => values_for(type),
+                :execution => execution_type(info[:type])
+              }.reject{|k,v| v.blank?}
+            }
+          end
+        end.compact
+      end
+
+      def values_for(facet_type)
+        Array(public_send("#{facet_type}_value"))
+      end
+    end
+  end
+end