Rebase to lastest upstream

README.markdown

@@ -1,6 +1,17 @@
 Tire
 =========
 
+---------------------------------------------------------------------------------------------------
+
+  NOTICE: This library has been renamed and retired in September 2013
+          ([read the explanation](https://github.com/karmi/retire/wiki/Tire-Retire)).
+
+  Have a look at the **<http://github.com/elasticsearch/elasticsearch-ruby>**
+  suite of gems, which will contain similar set of features for
+  ActiveRecord and Rails integration as Tire.
+
+---------------------------------------------------------------------------------------------------
+
 _Tire_ is a Ruby (1.8 or 1.9) client for the [Elasticsearch](http://www.elasticsearch.org/)
 search engine/database.
 
@@ -9,7 +20,7 @@ full-text search engine and database with
 [powerful aggregation features](http://www.elasticsearch.org/guide/reference/api/search/facets/),
 communicating by JSON over RESTful HTTP, based on [Lucene](http://lucene.apache.org/), written in Java.
 
-This Readme provides a brief overview of _Tire's_ features. The more detailed documentation is at <http://karmi.github.com/tire/>.
+This Readme provides a brief overview of _Tire's_ features. The more detailed documentation is at <http://karmi.github.com/retire/>.
 
 Both of these documents contain a lot of information. Please set aside some time to read them thoroughly, before you blindly dive into „somehow making it work“. Just skimming through it **won't work** for you. For more information, please see the project [Wiki](https://github.com/karmi/tire/wiki/_pages), search the [issues](https://github.com/karmi/tire/issues), and refer to the [integration test suite](https://github.com/karmi/tire/tree/master/test/integration).
 
@@ -52,7 +63,7 @@ To test-drive the core _Elasticsearch_ functionality, let's require the gem:
 ```
 
 Please note that you can copy these snippets from the much more extensive and heavily annotated file
-in [examples/tire-dsl.rb](http://karmi.github.com/tire/).
+in [examples/tire-dsl.rb](http://karmi.github.com/retire/).
 
 Also, note that we're doing some heavy JSON lifting here. _Tire_ uses the
 [_multi_json_](https://github.com/intridea/multi_json) gem as a generic JSON wrapper,
@@ -471,6 +482,10 @@ In this case, just wrap the `mapping` method in a `settings` one, passing it the
     end
 ```
 
+Note, that the index will be created with settings and mappings only when it doesn't exist yet.
+To re-create the index with correct configuration, delete it first: `URL.index.delete` and
+create it afterwards: `URL.create_elasticsearch_index`.
+
 It may well be reasonable to wrap the index creation logic declared with `Tire.index('urls').create`
 in a class method of your model, in a module method, etc, to have better control on index creation when
 bootstrapping the application with Rake tasks or when setting up the test suite.
@@ -573,6 +588,38 @@ control on how the documents are added to or removed from the index:
     end
 ```
 
+Sometimes, you might want to have complete control about the indexing process. In such situations,
+just drop down one layer and use the `Tire::Index#store` and `Tire::Index#remove` methods directly:
+
+```ruby
+    class Article < ActiveRecord::Base
+      acts_as_paranoid
+      include Tire::Model::Search
+
+      after_save do
+        if deleted_at.nil?
+          self.index.store self
+        else
+          self.index.remove self
+        end
+      end
+    end
+```
+
+Of course, in this way, you're still performing an HTTP request during your database transaction,
+which is not optimal for large-scale applications. In these situations, a better option would be processing
+the index operations in background, with something like [Resque](https://github.com/resque/resque) or
+[Sidekiq](https://github.com/mperham/sidekiq):
+
+```ruby
+    class Article < ActiveRecord::Base
+      include Tire::Model::Search
+
+      after_save    { Indexer::Index.perform_async(document) }
+      after_destroy { Indexer::Remove.perform_async(document) }
+    end
+```
+
 When you're integrating _Tire_ with ActiveRecord models, you should use the `after_commit`
 and `after_rollback` hooks to keep the index in sync with your database.
 
@@ -662,11 +709,11 @@ Are we saying you have to fiddle with this thing in a `rails console` or silly R
 Just call the included _Rake_ task on the command line:
 
 ```bash
-    $ rake environment tire:import CLASS='Article'
+    $ rake environment tire:import:all
 ```
 
-You can also force-import the data by deleting the index first (and creating it with mapping
-provided by the `mapping` block in your model):
+You can also force-import the data by deleting the index first (and creating it with
+correct settings and/or mappings provided by the `mapping` block in your model):
 
 ```bash
     $ rake environment tire:import CLASS='Article' FORCE=true
@@ -773,3 +820,5 @@ You can send feedback via [e-mail](mailto:karmi@karmi.cz) or via [Github Issues]
 -----
 
 [Karel Minarik](http://karmi.cz) and [contributors](http://github.com/karmi/tire/contributors)
+
+![](https://ga-beacon.appspot.com/UA-46901128-1/karmi/retire?pixel)

examples/rails-application-template.rb

@@ -13,8 +13,8 @@
 # * Git
 # * Ruby >= 1.8.7
 # * Rubygems
-# * Rails >= 3.0.7
-# * Sun Java 6 (for Elasticsearch)
+# * Rails >= 3
+# * Java 6 or 7 (for Elasticsearch)
 #
 #
 # Usage
@@ -181,14 +181,13 @@
 class Article < ActiveRecord::Base
   include Tire::Model::Search
   include Tire::Model::Callbacks
-
-  attr_accessible :title, :content, :published_on
 end
 CODE
 
 initializer 'tire.rb', <<-CODE
 Tire.configure do
-  logger STDERR
+  # url    'http://localhost:9200'
+  # logger STDERR
 end
 CODE
 
@@ -201,7 +200,7 @@ class Article < ActiveRecord::Base
 gsub_file 'app/controllers/articles_controller.rb', %r{# GET /articles/1$}, <<-CODE
   # GET /articles/search
   def search
-    @articles = Article.search params[:q]
+    @articles = Article.tire.search params[:q]
 
     render :action => "index"
   end
@@ -238,7 +237,7 @@ def search
 say_status  "Index", "Indexing the database...", :yellow
 puts        '-'*80, ''; sleep 0.5
 
-rake "environment tire:import CLASS='Article' FORCE=true"
+rake "environment tire:import:model CLASS='Article' FORCE=true"
 
 puts
 say_status  "Git", "Details about the application:", :yellow

examples/tire-dsl.rb

@@ -816,6 +816,156 @@ def self.search
   highlight :title, :body, :options => { :tag => '<strong class="highlight">' }
 end
 
+#### Suggest
+
+#
+# _Elasticsearch_
+# [suggest](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-suggesters.html)
+# feature suggests similar terms based on user input.
+# You can specify either the `term` or `phrase` suggester in the Tire DSL, or
+# use the `completion` suggester to get fast completions of user inputs, suitable
+# for auto-complete and instant search features.
+
+# Suggestion API is available either as standalone method or part of the search request.
+
+# To get search suggestions while doing a search, call the suggest API
+#
+s = Tire.search 'articles' do
+
+  # To define a suggest using the term suggester, first provide a custom name for the suggest.
+  #
+  suggest :suggest_title do
+    # Specify the input text.
+    #
+    text 'thrree blind mice'
+    # Then, define the field you want to use for suggestions and any options.
+    #
+    term :title, size: 3, sort: 'frequency'
+  end
+
+  # To define a suggest using the `phrase` suggest, use a different name.
+  suggest :phrase_suggest_title do
+    # Specify the text input text.
+    #
+    text 'thrree blind mice'
+    # Again, define the field you want to use for suggestions and any options.
+    #
+    phrase :title, size: 3 do
+      # Optinally, configure the `smoothing` option...
+      #
+      smoothing :stupid_backoff, discount: 0.5
+
+      # ...or the `generator` option.
+      generator :title, min_word_len: 1
+    end
+  end
+end
+
+# The results will be available in the `suggestions` property (which is iterable)
+#
+s.results.suggestions.each do |name, options|
+  puts "Suggestion returned for #{name}:\n"
+  options.each do |option|
+    puts "* Raw result: #{option}"
+  end
+end
+
+# You can also use helper methods available in suggestions results to get only
+# the suggested terms or phrases.
+#
+puts "Available corrections for suggest_title: #{s.results.suggestions.texts(:suggest_title).join(', ')}"
+
+# You can use the standalone API to achieve the same result:
+#
+s = Tire.suggest('articles') do
+
+  # Notice that for standalone API, the block method is `suggestion` rather than `suggest`:
+  #
+  suggestion :term_suggest do
+    text 'thrree'
+    term :title, size: 3, sort: 'frequency'
+  end
+
+end
+
+# You'll get the same object as above but as top level object
+#
+puts "Available corrections: #{s.results.texts.join(', ')}"
+
+#### Completion
+
+# In order to use _Elasticsearch_ completion you'll need to update your mappings to provide a field
+# with completion type. The example is adapted from this
+# [blog post](http://www.elasticsearch.org/blog/you-complete-me/).
+#
+index = Tire.index('hotels') do
+  delete
+
+  # Notice the type completion for the field _name_suggest_:
+  #
+  create :mappings => {
+      :hotel => {
+          :properties => {
+              :name => {:type => 'string'},
+              :city => {:type => 'string'},
+              :name_suggest => {:type => 'completion'}
+          }
+      }
+  }
+
+  # Let's add some documents into this index:
+  #
+  import([
+             {:id => '1', :type => 'hotel', :name => 'Mercure Hotel Munich', :city => 'Munich', :name_suggest => 'Mercure Hotel Munich'},
+             {:id => '2', :type => 'hotel', :name => 'Hotel Monaco', :city => 'Munich', :name_suggest => 'Hotel Monaco'},
+         ])
+  refresh
+
+end
+
+# We can ask for all hotels starting with a given prefix (such as "m") with this query:
+#
+s = Tire.suggest('hotels') do
+  suggestion 'complete' do
+    text 'm'
+    completion 'name_suggest'
+  end
+end
+
+# And retrieve results as above with the same object:
+#
+puts "There are #{s.results.texts.size} hotels starting with m:"
+s.results.texts.each do |hotel|
+  puts "* #{hotel}"
+end
+
+# You can use some advanced features of completion such as multiple inputs and unified output for
+# the same document.
+
+# If you add a document which has inputs and output values for the suggest field:
+#
+index.store({:id => '1', :type => 'hotel', :name => 'Mercure Hotel Munich', :city => 'Munich',
+             :name_suggest => {:input => ['Mercure Hotel Munich', 'Mercure Munich'], :output => 'Hotel Mercure'}})
+index.store({:id => '2', :type => 'hotel', :name => 'Hotel Monaco', :city => 'Munich',
+             :name_suggest => {:input => ['Monaco Munich', 'Hotel Monaco'], :output => 'Hotel Monaco'}})
+index.refresh
+
+# ... a completion request with the same input as above ...
+#
+s = Tire.suggest('hotels') do
+  suggestion 'complete' do
+    text 'm'
+    completion 'name_suggest'
+  end
+end
+
+# ... will match multiple inputs for the same document and return unified output in results:
+#
+puts "There are #{s.results.texts.size} hotels starting with m:"
+s.results.texts.each do |hotel|
+  puts "* #{hotel}"
+end
+
 #### Percolation
 
 # _Elasticsearch_ comes with one very interesting, and rather unique feature:

lib/tire.rb

@@ -24,17 +24,22 @@
 require 'tire/search'
 require 'tire/search/query'
 require 'tire/search/queries/match'
+require 'tire/search/queries/custom_filters_score'
 require 'tire/search/sort'
 require 'tire/search/facet'
 require 'tire/search/filter'
 require 'tire/search/highlight'
 require 'tire/search/scan'
 require 'tire/search/script_field'
+require 'tire/suggest'
+require 'tire/suggest/suggestion'
+require 'tire/delete_by_query'
 require 'tire/multi_search'
 require 'tire/count'
 require 'tire/results/pagination'
 require 'tire/results/collection'
 require 'tire/results/item'
+require 'tire/results/suggestions'
 require 'tire/index'
 require 'tire/alias'
 require 'tire/dsl'
@@ -43,6 +48,7 @@
 require 'tire/model/percolate'
 require 'tire/model/indexing'
 require 'tire/model/import'
+require 'tire/model/suggest'
 require 'tire/model/search'
 require 'tire/model/persistence/finders'
 require 'tire/model/persistence/attributes'