tire 0.5.4 → 0.5.5

data/.travis.yml

@@ -5,6 +5,7 @@
 language: ruby
 
 rvm:
+  - 2.0.0
   - 1.9.3
   - 1.8.7
   - ree
@@ -27,6 +28,8 @@ matrix:
       env: TEST_COMMAND="rake test:integration"
     - rvm: ree
       env: TEST_COMMAND="rake test:integration"
+  allow_failures:
+    - rvm: ree
 
 notifications:
   disable: true

data/README.markdown

@@ -1,12 +1,12 @@
 Tire
 =========
 
-_Tire_ is a Ruby (1.8 or 1.9) client for the [ElasticSearch](http://www.elasticsearch.org/)
+_Tire_ is a Ruby (1.8 or 1.9) client for the [Elasticsearch](http://www.elasticsearch.org/)
 search engine/database.
 
-_ElasticSearch_ is a scalable, distributed, cloud-ready, highly-available,
+_Elasticsearch_ is a scalable, distributed, cloud-ready, highly-available,
 full-text search engine and database with
-[powerfull aggregation features](http://www.elasticsearch.org/guide/reference/api/search/facets/),
+[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/>.
@@ -17,11 +17,11 @@ and [issues](https://github.com/karmi/tire/issues).
 Installation
 ------------
 
-OK. First, you need a running _ElasticSearch_ server. Thankfully, it's easy. Let's define easy:
+OK. First, you need a running _Elasticsearch_ server. Thankfully, it's easy. Let's define easy:
 
-    $ curl -k -L -o elasticsearch-0.19.0.tar.gz http://github.com/downloads/elasticsearch/elasticsearch/elasticsearch-0.19.0.tar.gz
-    $ tar -zxvf elasticsearch-0.19.0.tar.gz
-    $ ./elasticsearch-0.19.0/bin/elasticsearch -f
+    $ curl -k -L -o elasticsearch-0.20.2.tar.gz http://download.elasticsearch.org/elasticsearch/elasticsearch/elasticsearch-0.20.2.tar.gz
+    $ tar -zxvf elasticsearch-0.20.2.tar.gz
+    $ ./elasticsearch-0.20.2/bin/elasticsearch -f
 
 See, easy. On a Mac, you can also use _Homebrew_:
 
@@ -41,11 +41,11 @@ Of course, you can install it from the source as well:
 Usage
 -----
 
-_Tire_ exposes easy-to-use domain specific language for fluent communication with _ElasticSearch_.
+_Tire_ exposes easy-to-use domain specific language for fluent communication with _Elasticsearch_.
 
 It easily blends with your _ActiveModel_/_ActiveRecord_ classes for convenient usage in _Rails_ applications.
 
-To test-drive the core _ElasticSearch_ functionality, let's require the gem:
+To test-drive the core _Elasticsearch_ functionality, let's require the gem:
 
 ```ruby
     require 'rubygems'
@@ -102,7 +102,7 @@ for a specific document type:
 ```
 
 Of course, we may have large amounts of data, and it may be impossible or impractical to add them to the index
-one by one. We can use _ElasticSearch's_
+one by one. We can use _Elasticsearch's_
 [bulk storage](http://www.elasticsearch.org/guide/reference/api/bulk.html).
 Notice, that collection items must have an `id` property or method,
 and should have a `type` property, if you've set any specific mapping for the index.
@@ -344,7 +344,7 @@ When you set the log level to _debug_:
 the JSON responses are logged as well. This is not a great idea for production environment,
 but it's priceless when you want to paste a complicated transaction to the mailing list or IRC channel.
 
-The _Tire_ DSL tries hard to provide a strong Ruby-like API for the main _ElasticSearch_ features.
+The _Tire_ DSL tries hard to provide a strong Ruby-like API for the main _Elasticsearch_ features.
 
 By default, _Tire_ wraps the results collection in a enumerable `Results::Collection` class,
 and result items in a `Results::Item` class, which looks like a child of `Hash` and `Openstruct`,
@@ -357,7 +357,7 @@ If that seems like a great idea to you, there's a big chance you already have su
 
 One would bet it's an `ActiveRecord` or `ActiveModel` class, containing model of your Rails application.
 
-Fortunately, _Tire_ makes blending _ElasticSearch_ features into your models trivially possible.
+Fortunately, _Tire_ makes blending _Elasticsearch_ features into your models trivially possible.
 
 
 ActiveModel Integration
@@ -365,7 +365,7 @@ ActiveModel Integration
 
 If you're the type with no time for lengthy introductions, you can generate a fully working
 example Rails application, with an `ActiveRecord` model and a search form, to play with
-(it even downloads _ElasticSearch_ itself, generates the application skeleton and leaves you with
+(it even downloads _Elasticsearch_ itself, generates the application skeleton and leaves you with
 a _Git_ repository to explore the steps and the code):
 
     $ rails new searchapp -m https://raw.github.com/karmi/tire/master/examples/rails-application-template.rb
@@ -384,7 +384,7 @@ To make it searchable with _Tire_, just `include` it:
 When you now save a record:
 
 ```ruby
-    Article.create :title =>   "I Love ElasticSearch",
+    Article.create :title =>   "I Love Elasticsearch",
                    :content => "...",
                    :author =>  "Captain Nemo",
                    :published_on => Time.now
@@ -529,7 +529,7 @@ The easiest way is to customize the `to_json` serialization support of your mode
     class Article < ActiveRecord::Base
       # ...
 
-      include_root_in_json = false
+      self.include_root_in_json = false
       def to_indexed_json
         to_json :except => ['updated_at'], :methods => ['length']
       end
@@ -574,9 +574,12 @@ control on how the documents are added to or removed from the index:
     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.
+
 The results returned by `Article.search` are wrapped in the aforementioned `Item` class, by default.
-This way, we have a fast and flexible access to the properties returned from _ElasticSearch_ (via the
-`_source` or `fields` JSON properties). This way, we can index whatever JSON we like in _ElasticSearch_,
+This way, we have a fast and flexible access to the properties returned from _Elasticsearch_ (via the
+`_source` or `fields` JSON properties). This way, we can index whatever JSON we like in _Elasticsearch_,
 and retrieve it, simply, via the dot notation:
 
 ```ruby
@@ -588,18 +591,18 @@ and retrieve it, simply, via the dot notation:
 ```
 
 The `Item` instances masquerade themselves as instances of your model within a _Rails_ application
-(based on the `_type` property retrieved from _ElasticSearch_), so you can use them carefree;
+(based on the `_type` property retrieved from _Elasticsearch_), so you can use them carefree;
 all the `url_for` or `dom_id` helpers work as expected.
 
-If you need to access the “real” model (eg. to access its assocations or methods not
-stored in _ElasticSearch_), just load it from the database:
+If you need to access the “real” model (eg. to access its associations or methods not
+stored in _Elasticsearch_), just load it from the database:
 
 ```ruby
     puts article.load(:include => 'comments').comments.size
 ```
 
 You can see that _Tire_ stays as far from the database as possible. That's because it believes
-you have most of the data you want to display stored in _ElasticSearch_. When you need
+you have most of the data you want to display stored in _Elasticsearch_. When you need
 to eagerly load the records from the database itself, for whatever reason,
 you can do it with the `:load` option when searching:
 
@@ -636,14 +639,14 @@ so you can pass all the usual parameters to the `search` method in the controlle
     @articles = Article.search params[:q], :page => (params[:page] || 1)
 ```
 
-OK. Chances are, you have lots of records stored in your database. How will you get them to _ElasticSearch_? Easy:
+OK. Chances are, you have lots of records stored in your database. How will you get them to _Elasticsearch_? Easy:
 
 ```ruby
     Article.index.import Article.all
 ```
 
 This way, however, all your records are loaded into memory, serialized into JSON,
-and sent down the wire to _ElasticSearch_. Not practical, you say? You're right.
+and sent down the wire to _Elasticsearch_. Not practical, you say? You're right.
 
 Provided your model implements some sort of _pagination_ — and it probably does —, you can just run:
 
@@ -661,7 +664,7 @@ in chunks of 1000. If that number doesn't suit you, just provide a better one:
 Any other parameters you provide to the `import` method are passed down to the `paginate` method.
 
 Are we saying you have to fiddle with this thing in a `rails console` or silly Ruby scripts? No.
-Just call the included _Rake_ task on the commandline:
+Just call the included _Rake_ task on the command line:
 
 ```bash
     $ rake environment tire:import CLASS='Article'
@@ -674,7 +677,14 @@ provided by the `mapping` block in your model):
     $ rake environment tire:import CLASS='Article' FORCE=true
 ```
 
-When you'll spend more time with _ElasticSearch_, you'll notice how
+When importing records from multiple tables, you can fight the n+1 queries problem by passing
+`include` parameters to the `paginate` method:
+
+```bash
+    rake environment tire:import PARAMS='{:include => ["comments"]}' CLASS=Article FORCE=true
+```
+
+When you'll spend more time with _Elasticsearch_, you'll notice how
 [index aliases](http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases.html)
 are the best idea since the invention of inverted index.
 You can index your data into a fresh index (and possibly update an alias once everything's fine):
@@ -683,6 +693,16 @@ You can index your data into a fresh index (and possibly update an alias once ev
     $ rake environment tire:import CLASS='Article' INDEX='articles-2011-05'
 ```
 
+Finally, consider the Rake importing task just a convenient starting point. If you're loading
+substantial amounts of data, want better control on which data will be indexed, etc., use the
+lower-level Tire API with eg. `ActiveRecordBase#find_in_batches`:
+
+```ruby
+    Article.where("published_on > ?", Time.parse("2012-10-01")).find_in_batches do |group|
+      Tire.index("articles").import group
+    end
+```
+
 OK. All this time we have been talking about `ActiveRecord` models, since
 it is a reasonable _Rails_' default for the storage layer.
 
@@ -708,7 +728,7 @@ Well, things stay mostly the same:
 
     end
 
-    Article.create :title => 'I Love ElasticSearch'
+    Article.create :title => 'I Love Elasticsearch'
 
     Article.tire.search 'love'
 ```
@@ -723,9 +743,9 @@ database to store stuff like `{ :name => 'Tire', :tags => [ 'ruby', 'search' ] }
 Because all you need, really, is to just dump a JSON-representation of your data into a database and load it back again.
 Because you've noticed that _searching_ your data is a much more effective way of retrieval
 then constructing elaborate database query conditions.
-Because you have _lots_ of data and want to use _ElasticSearch's_ advanced distributed features.
+Because you have _lots_ of data and want to use _Elasticsearch's_ advanced distributed features.
 
-All good reasons to use _ElasticSearch_ as a schema-free and highly-scalable storage and retrieval/aggregation engine for your data.
+All good reasons to use _Elasticsearch_ as a schema-free and highly-scalable storage and retrieval/aggregation engine for your data.
 
 To use the persistence mode, we'll include the `Tire::Persistence` module in our class and define its properties;
 we can add the standard mapping declarations, set default values, or define casting for the property to create
@@ -759,7 +779,7 @@ and extensions to the core _Tire_ functionality — be sure to check them out.
 Other Clients
 -------------
 
-Check out [other _ElasticSearch_ clients](http://www.elasticsearch.org/guide/appendix/clients.html).
+Check out [other _Elasticsearch_ clients](http://www.elasticsearch.org/guide/appendix/clients.html).
 
 
 Feedback

data/examples/rails-application-template.rb

@@ -1,8 +1,8 @@
 # ===================================================================================================================
-# Template for generating a no-frills Rails application with support for ElasticSearch full-text search via Tire
+# Template for generating a no-frills Rails application with support for Elasticsearch full-text search via Tire
 # ===================================================================================================================
 #
-# This file creates a basic, fully working Rails application with support for ElasticSearch full-text search
+# This file creates a basic, fully working Rails application with support for Elasticsearch full-text search
 # via the Tire gem [http://github.com/karmi/tire].
 #
 # You DON'T NEED ELASTICSEARCH INSTALLED, it is installed and launched automatically by this script.
@@ -14,7 +14,7 @@
 # * Ruby >= 1.8.7
 # * Rubygems
 # * Rails >= 3.0.7
-# * Sun Java 6 (for ElasticSearch)
+# * Sun Java 6 (for Elasticsearch)
 #
 #
 # Usage
@@ -46,7 +46,7 @@ end
 at_exit do
   pid = File.read("#{destination_root}/tmp/pids/elasticsearch.pid") rescue nil
   if pid
-    say_status  "Stop", "ElasticSearch", :yellow
+    say_status  "Stop", "Elasticsearch", :yellow
     run "kill #{pid}"
   end
 end
@@ -62,7 +62,7 @@ file ".gitignore", <<-END.gsub(/  /, '')
   tmp/**/*
   config/database.yml
   db/*.sqlite3
-  vendor/elasticsearch-0.19.0/
+  vendor/elasticsearch-0.20.2/
 END
 
 git :init
@@ -71,32 +71,32 @@ git :commit => "-m 'Initial commit: Clean application'"
 
 unless (RestClient.get('http://localhost:9200') rescue false)
   COMMAND = <<-COMMAND.gsub(/^    /, '')
-    curl -k -L -# -o elasticsearch-0.19.0.tar.gz \
-      "http://github.com/downloads/elasticsearch/elasticsearch/elasticsearch-0.19.0.tar.gz"
-    tar -zxf elasticsearch-0.19.0.tar.gz
-    rm  -f   elasticsearch-0.19.0.tar.gz
-    ./elasticsearch-0.19.0/bin/elasticsearch -p #{destination_root}/tmp/pids/elasticsearch.pid
+    curl -k -L -# -o elasticsearch-0.20.2.tar.gz \
+      "http://github.com/downloads/elasticsearch/elasticsearch/elasticsearch-0.20.2.tar.gz"
+    tar -zxf elasticsearch-0.20.2.tar.gz
+    rm  -f   elasticsearch-0.20.2.tar.gz
+    ./elasticsearch-0.20.2/bin/elasticsearch -p #{destination_root}/tmp/pids/elasticsearch.pid
   COMMAND
 
   puts        "\n"
-  say_status  "ERROR", "ElasticSearch not running!\n", :red
+  say_status  "ERROR", "Elasticsearch not running!\n", :red
   puts        '-'*80
-  say_status  '',      "It appears that ElasticSearch is not running on this machine."
+  say_status  '',      "It appears that Elasticsearch is not running on this machine."
   say_status  '',      "Is it installed? Do you want me to install it for you with this command?\n\n"
   COMMAND.each_line { |l| say_status '', "$ #{l}" }
   puts
   say_status  '',      "(To uninstall, just remove the generated application directory.)"
   puts        '-'*80, ''
 
-  if yes?("Install ElasticSearch?", :bold)
+  if yes?("Install Elasticsearch?", :bold)
     puts
-    say_status  "Install", "ElasticSearch", :yellow
+    say_status  "Install", "Elasticsearch", :yellow
 
     commands = COMMAND.split("\n")
     exec     = commands.pop
     inside("vendor") do
       commands.each { |command| run command }
-      run "(#{exec})"  # Launch ElasticSearch in subshell
+      run "(#{exec})"  # Launch Elasticsearch in subshell
     end
   end
 end

data/examples/tire-dsl.rb

@@ -1,9 +1,9 @@
 # encoding: UTF-8
 #
 # **Tire** provides rich and comfortable Ruby API for the
-# [_ElasticSearch_](http://www.elasticsearch.org/) search engine/database.
+# [_Elasticsearch_](http://www.elasticsearch.org/) search engine/database.
 #
-# _ElasticSearch_ is a scalable, distributed, cloud-ready, highly-available
+# _Elasticsearch_ is a scalable, distributed, cloud-ready, highly-available
 # full-text search engine and database, communicating by JSON over RESTful HTTP,
 # based on [Lucene](http://lucene.apache.org/), written in Java.
 #
@@ -40,14 +40,14 @@ require 'tire'
 
 #### Prerequisites
 
-# We'll need a working and running _ElasticSearch_ server, of course. Thankfully, that's easy.
+# We'll need a working and running _Elasticsearch_ server, of course. Thankfully, that's easy.
 ( puts <<-"INSTALL" ; exit(1) ) unless (RestClient.get('http://localhost:9200') rescue false)
 
- [ERROR] You don’t appear to have ElasticSearch installed. Please install and launch it with the following commands:
+ [ERROR] You don’t appear to have Elasticsearch installed. Please install and launch it with the following commands:
 
- curl -k -L -o elasticsearch-0.19.0.tar.gz http://github.com/downloads/elasticsearch/elasticsearch/elasticsearch-0.19.0.tar.gz
- tar -zxvf elasticsearch-0.19.0.tar.gz
- ./elasticsearch-0.19.0/bin/elasticsearch -f
+ curl -k -L -o elasticsearch-0.20.2.tar.gz http://github.com/downloads/elasticsearch/elasticsearch/elasticsearch-0.20.2.tar.gz
+ tar -zxvf elasticsearch-0.20.2.tar.gz
+ ./elasticsearch-0.20.2/bin/elasticsearch -f
 INSTALL
 
 ### Storing and indexing documents
@@ -68,7 +68,7 @@ Tire.index 'articles' do
   store :title => 'One',   :tags => ['ruby'],           :published_on => '2011-01-01'
   store :title => 'Two',   :tags => ['ruby', 'python'], :published_on => '2011-01-02'
 
-  # We usually want to set a specific _type_ for the document in _ElasticSearch_.
+  # We usually want to set a specific _type_ for the document in _Elasticsearch_.
   # Simply setting a `type` property is OK.
   #
   store :type => 'article',
@@ -137,7 +137,7 @@ Tire.index 'articles' do
         #
         :id       => { :type => 'string', :index => 'not_analyzed', :include_in_all => false },
 
-        # ... set the boost or analyzer settings for the field, etc. The _ElasticSearch_ guide
+        # ... set the boost or analyzer settings for the field, etc. The _Elasticsearch_ guide
         # has [more information](http://elasticsearch.org/guide/reference/mapping/index.html).
         # Don't forget, that proper mapping is key to efficient and effective search.
         # But don't fret about getting the mapping right the first time, you won't.
@@ -154,7 +154,7 @@ end
 #### Bulk Indexing
 
 # Of course, we may have large amounts of data, and adding them to the index one by one really isn't the best idea.
-# We can use _ElasticSearch's_ [bulk API](http://www.elasticsearch.org/guide/reference/api/bulk.html)
+# We can use _Elasticsearch's_ [bulk API](http://www.elasticsearch.org/guide/reference/api/bulk.html)
 # for importing the data.
 
 # So, for demonstration purposes, let's suppose we have a simple collection of hashes to store.
@@ -197,7 +197,7 @@ end
 
 ### Searching
 
-# With the documents indexed and stored in the _ElasticSearch_ database, we can search them, finally.
+# With the documents indexed and stored in the _Elasticsearch_ database, we can search them, finally.
 #
 # _Tire_ exposes the search interface via simple domain-specific language.
 
@@ -289,7 +289,7 @@ end
 # We may use any valid [Lucene query syntax](http://lucene.apache.org/java/3_0_3/queryparsersyntax.html)
 # for the `query_string` queries.
 
-# For debugging our queries, we can display the JSON which is being sent to _ElasticSearch_.
+# For debugging our queries, we can display the JSON which is being sent to _Elasticsearch_.
 #
 #     {"query":{"query_string":{"query":"title:T*"}}}
 #
@@ -342,7 +342,7 @@ end
 #
 Tire.configure do
 
-  # First of all, we can configure the URL for _ElasticSearch_.
+  # First of all, we can configure the URL for _Elasticsearch_.
   #
   url "http://search.example.com"
 
@@ -362,7 +362,7 @@ end
 ### Complex Searching
 
 # Query strings are convenient for simple searches, but we may want to define our queries more expressively,
-# using the _ElasticSearch_ [Query DSL](http://www.elasticsearch.org/guide/reference/query-dsl/index.html).
+# using the _Elasticsearch_ [Query DSL](http://www.elasticsearch.org/guide/reference/query-dsl/index.html).
 #
 s = Tire.search('articles') do
 
@@ -471,7 +471,7 @@ Tire.search('articles') do
   end
 end
 
-# _ElasticSearch_ supports many types of [queries](http://www.elasticsearch.org/guide/reference/query-dsl/).
+# _Elasticsearch_ supports many types of [queries](http://www.elasticsearch.org/guide/reference/query-dsl/).
 #
 # Eventually, _Tire_ will support all of them. So far, only these are supported:
 #
@@ -487,7 +487,7 @@ end
 
 #### Faceted Search
 
-# _ElasticSearch_ makes it trivial to retrieve complex aggregated data from our index/database,
+# _Elasticsearch_ makes it trivial to retrieve complex aggregated data from our index/database,
 # so called [_facets_](http://www.elasticsearch.org/guide/reference/api/search/facets/index.html).
 
 # Let's say we want to display article counts for every tag in the database.
@@ -579,7 +579,7 @@ s.results.facets['global-tags']['terms'].each do |f|
   puts "#{f['term'].ljust(10)} #{f['count']}"
 end
 
-# _ElasticSearch_ supports many advanced types of facets, such as those for computing statistics or geographical distance.
+# _Elasticsearch_ supports many advanced types of facets, such as those for computing statistics or geographical distance.
 #
 # Eventually, _Tire_ will support all of them. So far, only these are supported:
 #
@@ -591,7 +591,7 @@ end
 # * [terms_stats](http://www.elasticsearch.org/guide/reference/api/search/facets/terms-stats-facet.html)
 # * [query](http://www.elasticsearch.org/guide/reference/api/search/facets/query-facet.html)
 
-# We have seen that _ElasticSearch_ facets enable us to fetch complex aggregations from our data.
+# We have seen that _Elasticsearch_ facets enable us to fetch complex aggregations from our data.
 #
 # They are frequently used for another feature, „faceted navigation“.
 # We can be combine query and facets with
@@ -777,7 +777,7 @@ end
 #### Highlighting
 
 # Often, we want to highlight the snippets matching our query in the displayed results.
-# _ElasticSearch_ provides rich
+# _Elasticsearch_ provides rich
 # [highlighting](http://www.elasticsearch.org/guide/reference/api/search/highlighting.html)
 # features, and _Tire_ makes them trivial to use.
 #
@@ -786,7 +786,7 @@ s = Tire.search 'articles' do
   # Let's search for documents containing word “Two” in their titles,
   query { string 'title:Two' }
 
-   # and instruct _ElasticSearch_ to highlight relevant snippets.
+   # and instruct _Elasticsearch_ to highlight relevant snippets.
    #
   highlight :title
 end
@@ -818,7 +818,7 @@ end
 
 #### Percolation
 
-# _ElasticSearch_ comes with one very interesting, and rather unique feature:
+# _Elasticsearch_ comes with one very interesting, and rather unique feature:
 # [_percolation_](http://www.elasticsearch.org/guide/reference/api/percolate.html).
 
 # It works in a „reverse search“ manner to regular search workflow of adding
@@ -848,7 +848,7 @@ index = Tire.index('weather') do
 end
 
 # Notice, that we have added a _tags_ field to the query document, because it behaves
-# just like any other document in _ElasticSearch_.
+# just like any other document in _Elasticsearch_.
 
 # We will refresh the `_percolator` index for immediate access.
 #
@@ -864,7 +864,7 @@ matches = index.percolate(:message => '[Warning] Extreme flooding expected after
 #
 puts "Matching queries: " + matches.inspect
 
-# We can filter the executed queries with a regular _ElasticSearch_ query passed as a block to
+# We can filter the executed queries with a regular _Elasticsearch_ query passed as a block to
 # the `percolate` method.
 #
 matches = index.percolate(:message => '[Warning] Extreme flooding expected after tsunami wave.') do
@@ -918,7 +918,7 @@ puts "Matching queries: " + response['matches'].inspect
 ### ActiveModel Integration
 
 # As you can see, [_Tire_](https://github.com/karmi/tire) supports the
-# main features of _ElasticSearch_ in Ruby.
+# main features of _Elasticsearch_ in Ruby.
 #
 # It allows you to create and delete indices, add documents, search them, retrieve the facets, highlight the results,
 # and comes with a usable logging facility.