estella 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bf61c93e5566773e32ae933239e245236cce24e3
+  data.tar.gz: c3d455dacea867bd1e53d325120991ff59cc0979
+SHA512:
+  metadata.gz: 56bb154fc881a5670a089247dbb4d83134cbbb9303707835a3138ae987d13385e3598c2b7841ce912e635d5177885cda1441e321db7854cfcc0df87765ee90ea
+  data.tar.gz: 4b6ad124cba5f0a4bfd777de3afcf81c6d17af16796ff160825b190a26359942450e1b657ef9024206e3e5c4831c378100355f0a3cfe5e0c2425d8816d1442f0

data/.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

data/.rspec

@@ -0,0 +1,5 @@
+--colour
+--drb
+--profile
+--format documentation
+

data/.rubocop.yml

@@ -0,0 +1,5 @@
+AllCops:
+  Exclude:
+    - vendor/**/*
+
+inherit_from: .rubocop_todo.yml

data/.rubocop_todo.yml

@@ -0,0 +1,78 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2017-01-24 13:49:04 -0500 using RuboCop version 0.47.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 3
+Metrics/AbcSize:
+  Max: 24
+
+# Offense count: 3
+# Configuration parameters: CountComments, ExcludedMethods.
+Metrics/BlockLength:
+  Max: 94
+
+# Offense count: 26
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
+# URISchemes: http, https
+Metrics/LineLength:
+  Max: 131
+
+# Offense count: 1
+# Configuration parameters: CountComments.
+Metrics/MethodLength:
+  Max: 14
+
+# Offense count: 3
+# Cop supports --auto-correct.
+# Configuration parameters: MaxKeyValuePairs.
+Performance/RedundantMerge:
+  Exclude:
+    - 'lib/estella/parser.rb'
+    - 'lib/estella/searchable.rb'
+
+# Offense count: 1
+Style/AccessorMethodName:
+  Exclude:
+    - 'lib/estella/helpers.rb'
+
+# Offense count: 1
+Style/ClassVars:
+  Exclude:
+    - 'lib/estella/helpers.rb'
+
+# Offense count: 7
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/estella/analysis.rb'
+    - 'lib/estella/helpers.rb'
+    - 'lib/estella/parser.rb'
+    - 'lib/estella/query.rb'
+    - 'lib/estella/searchable.rb'
+
+# Offense count: 3
+# Configuration parameters: MinBodyLength.
+Style/GuardClause:
+  Exclude:
+    - 'lib/estella/query.rb'
+    - 'lib/estella/searchable.rb'
+
+# Offense count: 9
+# Cop supports --auto-correct.
+Style/MutableConstant:
+  Exclude:
+    - 'lib/estella/analysis.rb'
+    - 'lib/estella/version.rb'
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+# SupportedStyles: only_raise, only_fail, semantic
+Style/SignalException:
+  Exclude:
+    - 'lib/estella/parser.rb'

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+
+cache: bundler
+
+rvm:
+  - 2.2.2
+
+before_install:
+  - gem update bundler
+  - "curl -O https://download.elasticsearch.org/elasticsearch/release/org/elasticsearch/distribution/deb/elasticsearch/2.1.1/elasticsearch-2.1.1.deb && sudo dpkg -i --force-confnew elasticsearch-2.1.1.deb"
+  - "echo 'script.inline: on' | sudo tee -a /etc/elasticsearch/elasticsearch.yml"
+  - "sudo /etc/init.d/elasticsearch start"
+  - "sleep 5"

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## Changelog
+
+### 0.2.1 (1/24/2017)
+
+* Initial public release as the `estella` gem - [@cavia](https://github.com/cavvia), [@mzikherman](https://github.com/mzikherman).

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Artsy Inc.
+
+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,195 @@
+# estella
+
+[![Gem Version](https://badge.fury.io/rb/estella.svg)](https://badge.fury.io/rb/estella)
+[![Build Status](https://travis-ci.org/artsy/estella.svg?branch=master)](https://travis-ci.org/artsy/estella)
+[![License Status](https://git.legal/projects/3493/badge.svg)](https://git.legal/projects/3493)
+
+Builds on [elasticsearch-model](https://github.com/elastic/elasticsearch-rails/tree/master/elasticsearch-model) to make your Ruby objects searchable with Elasticsearch. Provides fine-grained control of fields, analysis, filters, weightings and boosts.
+
+## Installation
+
+```
+gem 'estella'
+```
+
+The module will try to use Elasticsearch on `localhost:9200` by default. You can configure your global ES client like so:
+
+```ruby
+Elasticsearch::Model.client = Elasticsearch::Client.new host: 'foo.com', log: true
+```
+
+It is also configurable on a per model basis, see the [doc](https://github.com/elastic/elasticsearch-rails/tree/master/elasticsearch-model#the-elasticsearch-client).
+
+## Indexing
+
+Just include the `Estella::Searchable` module and add a `searchable` block in your ActiveRecord or Mongoid model declaring the fields to be indexed like so:
+
+```ruby
+class Artist < ActiveRecord::Base
+    include Estella::Searchable
+
+    searchable do
+      field :name, type: :string, analysis: Estella::Analysis::FULLTEXT_ANALYSIS, factor: 1.0
+      field :keywords, type: :string, analysis: ['snowball', 'shingle'], factor: 0.5
+      field :bio, using: :biography, type: :string, index: :not_analyzed
+      field :birth_date, type: :date
+      field :follows, type: :integer
+      field :published, type: :boolean, filter: true
+      boost :follows, modifier: 'log1p', factor: 1E-3
+    end
+    ...
+end
+```
+
+For a full understanding of the options available for field mappings, see the Elastic [mapping documentation](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/mapping.html).
+
+The `filter` option allows the field to be used as a filter at search time.
+
+You can optionally provide field weightings to be applied at search time using the `factor` option. These are multipliers.
+
+Document-level boosts can be applied with the `boost` declaration, see the [field_value_factor](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/query-dsl-function-score-query.html#function-field-value-factor) documentation for boost options.
+
+While `filter`, `boost` and `factor` are query options, Estella allows for their static declaration in the `searchable` block for simplicity - they will be applied at query time by default when using `#estella_search`.
+
+You can now create your index mappings with this migration:
+
+```ruby
+Artist.reload_index!
+```
+
+This uses a default index naming scheme based on your model name, which you can override simply by declaring the following in your model:
+
+```ruby
+index_name 'my_index_name'
+```
+
+Start indexing documents simply by creating or saving them:
+
+```ruby
+Artist.create(name: 'Frank Estella', keywords: ['art', 'minimalism'])
+```
+
+Estella adds `after_save` and `after_destroy` callbacks for inline indexing, override these callbacks if you'd like to do your indexing in a background process. For example:
+
+```ruby
+class Artist < ActiveRecord::Base
+  include Estella::Searchable
+
+  # disable estella inline callbacks
+  skip_callback(:save, :after, :es_index)
+  skip_callback(:destroy, :after, :es_delete)
+
+  # declare your own
+  after_save :delay_es_index
+  after_destroy :delay_es_delete
+
+  ...
+end
+```
+
+## Custom Analysis
+
+Estella defines `standard`, `snowball`, `ngram` and `shingle` analysers by default. These cover most search contexts, including auto-suggest. In order to enable full-text search for a field, use:
+
+```ruby
+analysis: Estella::Analysis::FULLTEXT_ANALYSIS
+```
+
+Or alternatively select your analysis by listing the analysers you want enabled for a given field:
+
+```ruby
+es_field :keywords, type: :string, analysis: ['snowball', 'shingle']
+```
+
+The searchable block takes a `settings` hash in case you require custom analysers or sharding (see [doc](https://www.elastic.co/guide/en/elasticsearch/guide/current/configuring-analyzers.html)):
+
+```ruby
+my_analysis = {
+  tokenizer: {
+    ...
+  },
+  filter: {
+    ...
+  }
+}
+
+my_settings = {
+  analysis: my_analysis,
+  index: {
+    number_of_shards: 1,
+    number_of_replicas: 1
+  }
+}
+
+searchable my_settings do
+  ...
+end
+```
+
+It will otherwise use Estella defaults.
+
+## Searching
+
+Finally perform full-text search:
+
+```ruby
+Artist.estella_search(term: 'frank')
+Artist.estella_search(term: 'minimalism')
+```
+
+Estella searches all analysed text fields by default, using a [multi_match](https://www.elastic.co/guide/en/elasticsearch/guide/current/multi-match-query.html) search. The search will return an array of database records in score order. If you'd like access to the raw Elasticsearch response data use the `raw` option:
+
+```ruby
+Artist.estella_search(term: 'frank', raw: true)
+```
+
+Estella supports filtering on `filter` fields and pagination:
+
+```ruby
+Artist.estella_search(term: 'frank', published: true)
+Artist.estella_search(term: 'frank', size: 10, from: 5)
+```
+
+If you'd like to customize your query further, you can extend `Estella::Query` and override the `query_definition`:
+
+```ruby
+class MyQuery < Estella::Query
+  def query_definition
+    {
+      multi_match: {
+        ...
+      }
+    }
+  end
+end
+```
+
+And then override class method `estella_search_query` to direct Estella to use your query object:
+
+```ruby
+class Artist < ActiveRecord::Base
+  include Estella::Searchable
+
+  searchable do
+    ...
+  end
+
+  def self.estella_search_query
+    MyQuery
+  end
+end
+
+Artist.estella_search (term: 'frank')
+```
+
+For further search customization, see the [elasticsearch dsl](https://github.com/elastic/elasticsearch-rails/tree/master/elasticsearch-model#the-elasticsearch-dsl).
+
+Estella works with any ActiveRecord or Mongoid compatible data models.
+
+## Contributing
+
+Just fork the repo and submit a pull request.
+
+## License
+
+Copyright (c) 2017 Artsy Inc., [MIT License](LICENSE).

data/RELEASING.md

@@ -0,0 +1,66 @@
+# Releasing Estella
+
+There're no hard rules about when to release estella. Release bug fixes frequenty, features not so frequently and breaking API changes rarely.
+
+### Release
+
+Run tests, check that all tests succeed locally.
+
+```
+bundle install
+rake
+```
+
+Check that the last build succeeded in [Travis CI](https://travis-ci.org/dblock/estella) for all supported platforms.
+
+Increment the version, modify [lib/estella/version.rb](lib/estella/version.rb).
+
+*  Increment the third number if the release has bug fixes and/or very minor features, only (eg. change `0.2.1` to `0.2.2`).
+*  Increment the second number if the release contains major features or breaking API changes (eg. change `0.2.1` to `0.3.0`).
+
+Change "Next Release" in [CHANGELOG.md](CHANGELOG.md) to the new version.
+
+```
+### 0.2.2 (1/17/2017)
+```
+
+Remove the line with "Your contribution here.", since there will be no more contributions to this release.
+
+Commit your changes.
+
+```
+git add README.md CHANGELOG.md lib/estella/version.rb
+git commit -m "Preparing for release, 0.2.2."
+git push origin master
+```
+
+Release.
+
+```
+$ rake release
+
+estella 0.2.2 built to pkg/estella-0.2.2.gem.
+Tagged v0.2.2.
+Pushed git commits and tags.
+Pushed estella 0.2.2 to rubygems.org.
+```
+
+### Prepare for the Next Version
+
+Increment the third version number in [lib/estella/version.rb](lib/estella/version.rb).
+
+Add the next release to [CHANGELOG.md](CHANGELOG.md).
+
+```
+### 0.2.3 (Next)
+
+* Your contribution here.
+```
+
+Comit your changes.
+
+```
+git add CHANGELOG.md lib/estella/version.rb
+git commit -m "Preparing for next development iteration, 0.2.3."
+git push origin master
+```

data/Rakefile

@@ -0,0 +1,16 @@
+require 'rubygems'
+require 'bundler/gem_tasks'
+
+Bundler.setup :default, :development
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new(:rubocop)
+
+task default: [:rubocop, :spec]

data/estella.gemspec

@@ -0,0 +1,27 @@
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'estella/version'
+
+Gem::Specification.new do |gem|
+  gem.name = 'estella'
+  gem.homepage = 'https://github.com/artsy/estella'
+  gem.license = 'MIT'
+  gem.summary = %(Make your Ruby objects searchable with Elasticsearch.)
+  gem.version = Estella::VERSION
+  gem.description = 'Make your Ruby objects searchable with Elasticsearch.'
+  gem.email = ['anil@artsy.net']
+  gem.authors = ['Anil Bawa-Cavia', 'Matt Zikherman']
+
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- spec/*`.split("\n")
+
+  gem.add_runtime_dependency 'elasticsearch-model'
+  gem.add_runtime_dependency 'activesupport'
+  gem.add_runtime_dependency 'activemodel'
+
+  gem.add_development_dependency 'rake', '~> 11.0'
+  gem.add_development_dependency 'activerecord'
+  gem.add_development_dependency 'rspec', '~> 3.1.0'
+  gem.add_development_dependency 'rspec-expectations'
+  gem.add_development_dependency 'sqlite3'
+  gem.add_development_dependency 'rubocop', '0.47.1'
+end

data/lib/estella/analysis.rb

@@ -0,0 +1,61 @@
+module Estella
+  module Analysis
+    # Default Elasticsearch analysers
+    extend ActiveSupport::Concern
+
+    FRONT_NGRAM_FILTER =
+      { type: 'edgeNGram', min_gram: 2, max_gram: 15, side: 'front' }
+
+    DEFAULT_ANALYZER =
+      { type: 'custom', tokenizer: 'standard_tokenizer', filter: %w(lowercase asciifolding) }
+
+    SNOWBALL_ANALYZER =
+      { type: 'custom', tokenizer: 'standard_tokenizer', filter: %w(lowercase asciifolding snowball) }
+
+    SHINGLE_ANALYZER =
+      { type: 'custom', tokenizer: 'standard_tokenizer', filter: %w(shingle lowercase asciifolding) }
+
+    NGRAM_ANALYZER =
+      { type: 'custom', tokenizer: 'standard_tokenizer', filter: %w(lowercase asciifolding front_ngram_filter) }
+
+    DEFAULT_ANALYSIS = {
+      tokenizer: {
+        standard_tokenizer: { type: 'standard' }
+      },
+      filter: {
+        front_ngram_filter: FRONT_NGRAM_FILTER
+      },
+      analyzer: {
+        default_analyzer:   DEFAULT_ANALYZER,
+        snowball_analyzer:  SNOWBALL_ANALYZER,
+        shingle_analyzer:   SHINGLE_ANALYZER,
+        ngram_analyzer:     NGRAM_ANALYZER,
+        search_analyzer:    DEFAULT_ANALYZER
+      }
+    }
+
+    DEFAULT_FIELDS = {
+      default: { type: 'string', analyzer: 'default_analyzer' },
+      snowball: { type: 'string', analyzer: 'snowball_analyzer' },
+      shingle: { type: 'string', analyzer: 'shingle_analyzer' },
+      ngram: { type: 'string', analyzer: 'ngram_analyzer', search_analyzer: 'search_analyzer' }
+    }
+
+    DEFAULT_FIELD_FACTORS = {
+      default: 10,
+      ngram: 10,
+      snowball: 3,
+      shingle: 2,
+      search: 2
+    }
+
+    FULLTEXT_ANALYSIS = DEFAULT_FIELDS.keys
+
+    DEFAULT_SETTINGS = if defined? Rails && Rails.env == 'test'
+                         # Ensure no sharding in test env in order to enforce deterministic scores.
+                         { analysis: DEFAULT_ANALYSIS, index: { number_of_shards: 1, number_of_replicas: 1 } }
+                       else
+                         { analysis: DEFAULT_ANALYSIS }
+                       end
+  end
+end

data/lib/estella/helpers.rb

@@ -0,0 +1,94 @@
+module Estella
+  module Helpers
+    extend ActiveSupport::Concern
+
+    @@types = []
+
+    included do
+      index_name search_index_name
+
+      after_save :es_index
+      after_destroy :es_delete
+
+      attr_accessor :es_indexing
+
+      @@types << self
+    end
+
+    # track dependent classes for spec support
+    def self.types
+      @@types
+    end
+
+    def es_index
+      self.es_indexing = true
+      __elasticsearch__.index_document
+    ensure
+      self.es_indexing = nil
+    end
+
+    def es_delete
+      es_delete_document id
+    end
+
+    def es_transform
+      { index: { _id: id.to_s, data: as_indexed_json } }
+    end
+
+    module ClassMethods
+      ## Searching
+
+      def stella_raw_search(params = {})
+        __elasticsearch__.search(estella_query(params))
+      end
+
+      # @return an array of database records mapped using an adapter
+      def estella_search(params = {})
+        rsp = stella_raw_search(params)
+        params[:raw] ? rsp.response : rsp.records.to_a
+      end
+
+      ## Indexing
+
+      # default index naming scheme is pluralized model_name
+      def search_index_name
+        model_name.route_key
+      end
+
+      def batch_to_bulk(batch_of_ids)
+        find(batch_of_ids).map(&:es_transform)
+      end
+
+      def bulk_index(batch_of_ids)
+        __elasticsearch__.client.bulk index: index_name, type: model_name.element, body: batch_to_bulk(batch_of_ids)
+      end
+
+      def index_exists?
+        __elasticsearch__.client.indices.exists index: index_name
+      end
+
+      def reload_index!
+        __elasticsearch__.client.indices.delete index: index_name if index_exists?
+        __elasticsearch__.client.indices.create index: index_name, body: { settings: settings.to_hash, mappings: mappings.to_hash }
+      end
+
+      def recreate_index!
+        reload_index!
+        import
+        refresh_index!
+      end
+
+      def refresh_index!
+        __elasticsearch__.refresh_index!
+      end
+
+      def set_index_alias!(name)
+        __elasticsearch__.client.indices.put_alias index: index_name, name: name
+      end
+
+      def es_delete_document(id)
+        __elasticsearch__.client.delete type: document_type, id: id, index: index_name
+      end
+    end
+  end
+end

data/lib/estella/parser.rb

@@ -0,0 +1,27 @@
+module Estella
+  class Parser
+    def initialize(model)
+      @model = model
+    end
+
+    # document level boost
+    # @see https://www.elastic.co/guide/en/elasticsearch/guide/current/boosting-by-popularity.html
+    def boost(name, opts = {})
+      fail ArgumentError, 'Boost field is not indexed!' unless @model.indexed_fields.include? name
+      unless (opts.keys & [:modifier, :factor]).length == 2
+        fail ArgumentError, 'Please supply a modifier and a factor for your boost!'
+      end
+      @model.field_boost = { boost: { field: name }.merge(opts) }
+    end
+
+    # index a field
+    def field(name, opts = {})
+      using = opts[:using] || name
+      analysis = opts[:analysis] & @model.default_analysis_fields.keys
+      opts[:fields] ||= Hash[analysis.zip(@model.default_analysis_fields.values_at(*analysis))] if analysis
+
+      @model.indexed_json.merge!(name => using)
+      @model.indexed_fields.merge!(name => opts)
+    end
+  end
+end

data/lib/estella/query.rb

@@ -0,0 +1,125 @@
+module Estella
+  class Query
+    # Constructs a search query for ES
+    attr_accessor :query
+    attr_reader :params
+
+    def initialize(params)
+      @params = params
+      @query = {
+        _source: false,
+        query: {},
+        filter: {
+          bool: { must: [], must_not: [] }
+        },
+        aggregations: {}
+      }
+      add_query
+      add_filters
+      add_pagination
+      add_aggregations if params[:aggregations]
+      add_sort
+    end
+
+    # override if needed
+    def add_aggregations; end
+
+    # override if needed
+    def add_sort; end
+
+    def must(filter)
+      query[:filter][:bool][:must] << filter
+    end
+
+    def exclude(filter)
+      query[:filter][:bool][:must_not] << filter
+    end
+
+    def add_pagination
+      query[:size] = params[:size] if params[:size]
+      query[:from] = params[:from] if params[:from]
+    end
+
+    def add_query
+      if params[:term] && params[:indexed_fields]
+        add_term_query
+      else
+        query[:query] = { match_all: {} }
+      end
+    end
+
+    # fulltext search across all string fields
+    def add_term_query
+      query[:query] = {
+        function_score: {
+          query: query_definition
+        }
+      }
+
+      add_field_boost
+    end
+
+    def query_definition
+      {
+        multi_match: {
+          type: 'most_fields',
+          fields: term_search_fields,
+          query: params[:term]
+        }
+      }
+    end
+
+    def add_field_boost
+      if params[:boost]
+        query[:query][:function_score][:field_value_factor] = {
+          field: params[:boost][:field],
+          modifier: params[:boost][:modifier],
+          factor: params[:boost][:factor]
+        }
+
+        if params[:boost][:max]
+          query[:query][:function_score][:max_boost] = params[:boost][:max]
+        end
+      end
+    end
+
+    def field_factors
+      Estella::Analysis::DEFAULT_FIELD_FACTORS
+    end
+
+    # search all analysed string fields by default
+    # boost them by factor if provided
+    def term_search_fields
+      params[:indexed_fields]
+        .select { |_, opts| opts[:type].to_s == 'string' }
+        .reject { |_, opts| opts[:analysis].nil? }
+        .map do |field, opts|
+          opts[:analysis].map do |analyzer|
+            factor = field_factors[analyzer] * opts.fetch(:factor, 1.0)
+            "#{field}.#{analyzer}^#{factor}"
+          end
+        end
+        .flatten
+    end
+
+    def add_filters
+      if params[:indexed_fields]
+        params[:indexed_fields].each do |field, opts|
+          must term: { field => params[field] } if opts[:filter] && params[field]
+        end
+      end
+    end
+
+    def bool_filter(field, param)
+      if param
+        { term: { field => true } }
+      elsif !param.nil?
+        { term: { field => false } }
+      end
+    end
+
+    def add_bool_filter(field, param)
+      must bool_filter(field, param) if bool_filter(field, param)
+    end
+  end
+end

data/lib/estella/searchable.rb

@@ -0,0 +1,87 @@
+module Estella
+  module Searchable
+    # Makes your ActiveRecord model searchable via Elasticsearch
+    #
+    # Just include a block in your model like so:
+    #
+    # class Artist < ActiveRecord::Base
+    #   searchable do
+    #     field :name, type: :string, using: :my_attr, analysis: Estella::Analysis::FULLTEXT_ANALYSIS
+    #     field :follows, type: :integer
+    #     ...
+    #     boost :follows, modifier: 'log1p', factor: 1E-3
+    #   end
+    # end
+    #
+    # Document boosts are optional.
+    # You can now create your index with the following migration:
+    #
+    # Artist.reload_index!
+    # Artist.import
+    #
+    # And perform full-text search using:
+    #
+    # Artist.estella_search(term: x)
+    #
+    extend ActiveSupport::Concern
+
+    included do
+      include Elasticsearch::Model
+      include Estella::Helpers
+      include Estella::Analysis
+
+      @indexed_json = {}
+      @indexed_fields = {}
+      @field_boost = {}
+
+      class << self
+        attr_accessor :indexed_json, :indexed_fields, :field_boost
+      end
+
+      def self.estella_query(params = {})
+        params.merge!(field_boost)
+        params.merge!(indexed_fields: indexed_fields)
+        estella_search_query.new(params).query
+      end
+
+      def self.estella_search_query
+        Estella::Query
+      end
+    end
+
+    def as_indexed_json(_options = {})
+      schema = self.class.indexed_json
+      Hash[schema.keys.zip(schema.values.map { |v| v.respond_to?(:call) ? instance_exec(&v) : send(v) })]
+    end
+
+    module ClassMethods
+      # support for mongoid::slug
+      # indexes slug attribue by default
+      def index_slug
+        if defined? slug
+          indexed_fields.merge!(slug: { type: :string, index: :not_analyzed })
+          indexed_json.merge!(slug: :slug)
+        end
+      end
+
+      def default_analysis_fields
+        Estella::Analysis::DEFAULT_FIELDS
+      end
+
+      # sets up mappings and settings for index
+      def searchable(settings = Estella::Analysis::DEFAULT_SETTINGS, &block)
+        Estella::Parser.new(self).instance_eval(&block)
+        index_slug
+        indexed_fields = @indexed_fields
+
+        settings(settings) do
+          mapping do
+            indexed_fields.each do |name, opts|
+              indexes name, opts.except(:analysis, :using, :factor, :filter)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/estella/version.rb

@@ -0,0 +1,3 @@
+module Estella
+  VERSION = '0.2.1'
+end

data/lib/estella.rb

@@ -0,0 +1,8 @@
+require 'active_support'
+require 'active_model'
+require 'elasticsearch/model'
+require 'estella/query'
+require 'estella/helpers'
+require 'estella/analysis'
+require 'estella/parser'
+require 'estella/searchable'

data/spec/searchable_spec.rb

@@ -0,0 +1,108 @@
+require 'spec_helper'
+require 'estella'
+require 'active_record'
+
+describe Estella::Searchable, type: :model do
+  before do
+    ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+  end
+
+  describe 'searchable model', elasticsearch: true do
+    before do
+      class SearchableModel < ActiveRecord::Base
+        include Estella::Searchable
+
+        def self.slug
+          # mongoid::slug support
+          'foo'
+        end
+
+        searchable do
+          field :title, type: :string, analysis: Estella::Analysis::FULLTEXT_ANALYSIS, factor: 1.0
+          field :keywords, type: :string, analysis: [:default, :snowball], factor: 0.5
+          field :follows_count, type: :integer
+          field :published, type: :boolean, filter: true
+
+          boost :follows_count, modifier: 'log2p', factor: 5E-4, max: 1.0
+        end
+      end
+
+      ActiveRecord::Schema.define(version: 1) do
+        create_table(:searchable_models) do |t|
+          t.string :title
+          t.string :keywords
+          t.string :slug
+          t.boolean :published
+          t.integer :follows_count, default: 0
+        end
+      end
+
+      SearchableModel.reload_index!
+      @jez = SearchableModel.create(title: 'jeremy corbyn', keywords: ['jez'])
+      @tez = SearchableModel.create(title: 'theresa may', keywords: ['tez'])
+      SearchableModel.refresh_index!
+    end
+    it 'returns relevant results' do
+      expect(SearchableModel.all.size).to eq(2)
+      expect(SearchableModel.estella_search(term: 'jeremy')).to eq([@jez])
+      expect(SearchableModel.estella_search(term: 'theresa')).to eq([@tez])
+    end
+    it 'uses ngram analysis by default' do
+      expect(SearchableModel.estella_search(term: 'jer')).to eq([@jez])
+      expect(SearchableModel.estella_search(term: 'there')).to eq([@tez])
+    end
+    it 'searches all text fields by default' do
+      expect(SearchableModel.estella_search(term: 'jez')).to eq([@jez])
+    end
+    it 'boosts on follows_count' do
+      popular_jeremy = SearchableModel.create(title: 'jeremy corban', follows_count: 20_000)
+      SearchableModel.refresh_index!
+      expect(SearchableModel.estella_search(term: 'jeremy')).to eq([popular_jeremy, @jez])
+    end
+    it 'uses factor option to weight fields' do
+      @dude = SearchableModel.create(keywords: ['dude'])
+      @dude2 = SearchableModel.create(title: 'dude')
+      SearchableModel.refresh_index!
+      expect(SearchableModel.estella_search(term: 'dude')).to eq([@dude2, @dude])
+    end
+    it 'returns raw response when raw option is set' do
+      expect(SearchableModel.estella_search(term: 'jeremy', raw: true).hits.hits.first['_id']).to eq(@jez.id.to_s)
+    end
+    it 'indexes slug field by default' do
+      SearchableModel.create(title: 'liapunov', slug: 'liapunov')
+      SearchableModel.refresh_index!
+      expect(SearchableModel.mappings.to_hash[:searchable_model][:properties].keys.include?(:slug)).to eq true
+    end
+    it 'supports boolean filters' do
+      @liapunov = SearchableModel.create(title: 'liapunov', published: true)
+      SearchableModel.create(title: 'liapunov unpublished')
+      SearchableModel.refresh_index!
+      expect(SearchableModel.estella_search(published: true)).to eq [@liapunov]
+    end
+    it 'does not override field method on class' do
+      expect(SearchableModel.methods.include?(:field)).to eq(false)
+    end
+  end
+
+  describe 'configuration errors' do
+    it 'raises error when boost field is invalid' do
+      expect do
+        class BadSearchableModel < ActiveRecord::Base
+          include Estella::Searchable
+          searchable { boost :follows_count }
+        end
+      end.to raise_error(ArgumentError, 'Boost field is not indexed!')
+    end
+    it 'raises error when boost params are not set' do
+      expect do
+        class BadSearchableModel < ActiveRecord::Base
+          include Estella::Searchable
+          searchable do
+            field :follows_count, type: 'integer'
+            boost :follows_count
+          end
+        end
+      end.to raise_error(ArgumentError, 'Please supply a modifier and a factor for your boost!')
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+require 'active_support'
+require 'active_model'
+require 'rspec'
+
+require File.expand_path('../../lib/estella.rb', __FILE__)
+
+RSpec.configure do |config|
+  config.mock_with :rspec do |c|
+    c.syntax = :expect
+  end
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+
+  config.raise_errors_for_deprecations!
+
+  config.before(:context, elasticsearch: true) do
+    Elasticsearch::Model.client = Elasticsearch::Client.new
+    Estella::Helpers.types.each { |type| type.__elasticsearch__.client = nil } # clear memoized clients
+  end
+end

metadata

@@ -0,0 +1,194 @@
+--- !ruby/object:Gem::Specification
+name: estella
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Anil Bawa-Cavia
+- Matt Zikherman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-01-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: elasticsearch-model
+  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: activesupport
+  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: activemodel
+  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: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.47.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.47.1
+description: Make your Ruby objects searchable with Elasticsearch.
+email:
+- anil@artsy.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".rubocop_todo.yml"
+- ".travis.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- RELEASING.md
+- Rakefile
+- estella.gemspec
+- lib/estella.rb
+- lib/estella/analysis.rb
+- lib/estella/helpers.rb
+- lib/estella/parser.rb
+- lib/estella/query.rb
+- lib/estella/searchable.rb
+- lib/estella/version.rb
+- spec/searchable_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/artsy/estella
+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: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Make your Ruby objects searchable with Elasticsearch.
+test_files:
+- spec/searchable_spec.rb
+- spec/spec_helper.rb