Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 772 lines (579 sloc) 26.412 kb
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
1 Tire
5b01d11 @karmi Added README
karmi authored
2 =========
3
62f8cd1 @karmi [DOC] Added note about 1.8 and 1.9 compatibility
karmi authored
4 _Tire_ is a Ruby (1.8 or 1.9) client for the [ElasticSearch](http://www.elasticsearch.org/)
5 search engine/database.
5b01d11 @karmi Added README
karmi authored
6
6da9265 @karmi [DOC] Updating the README; removing bullshit, better wording of features...
karmi authored
7 _ElasticSearch_ is a scalable, distributed, cloud-ready, highly-available,
dea722b @karmi [DOC] Readme updates
karmi authored
8 full-text search engine and database with
9 [powerfull aggregation features](http://www.elasticsearch.org/guide/reference/api/search/facets/),
10 communicating by JSON over RESTful HTTP, based on [Lucene](http://lucene.apache.org/), written in Java.
5b01d11 @karmi Added README
karmi authored
11
dea722b @karmi [DOC] Readme updates
karmi authored
12 This Readme provides a brief overview of _Tire's_ features. The more detailed documentation is at <http://karmi.github.com/tire/>.
7ece651 @karmi [DOC] Added a caveat for lazy readers to the beginning of the Readme
karmi authored
13
dea722b @karmi [DOC] Readme updates
karmi authored
14 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 refer to the [integration test suite](https://github.com/karmi/tire/tree/master/test/integration)
15 and [issues](https://github.com/karmi/tire/issues).
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
16
5b01d11 @karmi Added README
karmi authored
17 Installation
18 ------------
19
7ece651 @karmi [DOC] Added a caveat for lazy readers to the beginning of the Readme
karmi authored
20 OK. First, you need a running _ElasticSearch_ server. Thankfully, it's easy. Let's define easy:
5b01d11 @karmi Added README
karmi authored
21
18b249a @pacoguzman Updated documentation and Rails template to use ElasticSearch version 0....
pacoguzman authored
22 $ curl -k -L -o elasticsearch-0.17.6.tar.gz http://github.com/downloads/elasticsearch/elasticsearch/elasticsearch-0.17.6.tar.gz
23 $ tar -zxvf elasticsearch-0.17.6.tar.gz
24 $ ./elasticsearch-0.17.6/bin/elasticsearch -f
5b01d11 @karmi Added README
karmi authored
25
7ece651 @karmi [DOC] Added a caveat for lazy readers to the beginning of the Readme
karmi authored
26 See, easy. On a Mac, you can also use _Homebrew_:
c993ce2 @karmi [DOC] Updated README
karmi authored
27
28 $ brew install elasticsearch
29
7ece651 @karmi [DOC] Added a caveat for lazy readers to the beginning of the Readme
karmi authored
30 Now, let's install the gem via Rubygems:
5b01d11 @karmi Added README
karmi authored
31
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
32 $ gem install tire
5b01d11 @karmi Added README
karmi authored
33
c993ce2 @karmi [DOC] Updated README
karmi authored
34 Of course, you can install it from the source as well:
5b01d11 @karmi Added README
karmi authored
35
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
36 $ git clone git://github.com/karmi/tire.git
37 $ cd tire
5b01d11 @karmi Added README
karmi authored
38 $ rake install
39
40
41 Usage
42 -----
43
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
44 _Tire_ exposes easy-to-use domain specific language for fluent communication with _ElasticSearch_.
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
45
bad6bc6 @karmi [DOC] Updated the Readme
karmi authored
46 It easily blends with your _ActiveModel_/_ActiveRecord_ classes for convenient usage in _Rails_ applications.
5b01d11 @karmi Added README
karmi authored
47
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
48 To test-drive the core _ElasticSearch_ functionality, let's require the gem:
5b01d11 @karmi Added README
karmi authored
49
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
50 ```ruby
5b01d11 @karmi Added README
karmi authored
51 require 'rubygems'
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
52 require 'tire'
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
53 ```
5b01d11 @karmi Added README
karmi authored
54
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
55 Please note that you can copy these snippets from the much more extensive and heavily annotated file
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
56 in [examples/tire-dsl.rb](http://karmi.github.com/tire/).
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
57
8b4401b @karmi [DOC] Added information on the "multi_json" usage into README and websit...
karmi authored
58 Also, note that we're doing some heavy JSON lifting here. _Tire_ uses the
59 [_multi_json_](https://github.com/intridea/multi_json) gem as a generic JSON wrapper,
60 which allows you to use your preferred JSON library. We'll use the
61 [_yajl-ruby_](https://github.com/brianmario/yajl-ruby) gem in the full on mode here:
62
63 ```ruby
64 require 'yajl/json_gem'
65 ```
66
dea722b @karmi [DOC] Readme updates
karmi authored
67 Let's create an index named `articles` and store/index some documents:
5b01d11 @karmi Added README
karmi authored
68
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
69 ```ruby
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
70 Tire.index 'articles' do
5b01d11 @karmi Added README
karmi authored
71 delete
72 create
73
74 store :title => 'One', :tags => ['ruby']
75 store :title => 'Two', :tags => ['ruby', 'python']
76 store :title => 'Three', :tags => ['java']
77 store :title => 'Four', :tags => ['ruby', 'php']
78
79 refresh
80 end
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
81 ```
5b01d11 @karmi Added README
karmi authored
82
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
83 We can also create the index with custom
84 [mapping](http://www.elasticsearch.org/guide/reference/api/admin-indices-create-index.html)
85 for a specific document type:
1e4330d @karmi Added information about specifying mapping when creating an index
karmi authored
86
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
87 ```ruby
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
88 Tire.index 'articles' do
4a2b77a @sbeckeriv [DOC] Added more consistent example of bulk importing documents into ind...
sbeckeriv authored
89 delete
90
1e4330d @karmi Added information about specifying mapping when creating an index
karmi authored
91 create :mappings => {
92 :article => {
93 :properties => {
94 :id => { :type => 'string', :index => 'not_analyzed', :include_in_all => false },
3b2fb47 @karmi README updates
karmi authored
95 :title => { :type => 'string', :boost => 2.0, :analyzer => 'snowball' },
96 :tags => { :type => 'string', :analyzer => 'keyword' },
97 :content => { :type => 'string', :analyzer => 'snowball' }
1e4330d @karmi Added information about specifying mapping when creating an index
karmi authored
98 }
99 }
100 }
101 end
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
102 ```
1e4330d @karmi Added information about specifying mapping when creating an index
karmi authored
103
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
104 Of course, we may have large amounts of data, and it may be impossible or impractical to add them to the index
4a2b77a @sbeckeriv [DOC] Added more consistent example of bulk importing documents into ind...
sbeckeriv authored
105 one by one. We can use _ElasticSearch's_
106 [bulk storage](http://www.elasticsearch.org/guide/reference/api/bulk.html).
107 Notice, that collection items must have an `id` property or method,
108 and should have a `type` property, if you've set any specific mapping for the index.
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
109
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
110 ```ruby
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
111 articles = [
4a2b77a @sbeckeriv [DOC] Added more consistent example of bulk importing documents into ind...
sbeckeriv authored
112 { :id => '1', :type => 'article', :title => 'one', :tags => ['ruby'] },
113 { :id => '2', :type => 'article', :title => 'two', :tags => ['ruby', 'python'] },
114 { :id => '3', :type => 'article', :title => 'three', :tags => ['java'] },
115 { :id => '4', :type => 'article', :title => 'four', :tags => ['ruby', 'php'] }
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
116 ]
117
4a2b77a @sbeckeriv [DOC] Added more consistent example of bulk importing documents into ind...
sbeckeriv authored
118 Tire.index 'articles' do
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
119 import articles
120 end
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
121 ```
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
122
4a2b77a @sbeckeriv [DOC] Added more consistent example of bulk importing documents into ind...
sbeckeriv authored
123 We can easily manipulate the documents before storing them in the index, by passing a block to the
124 `import` method, like this:
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
125
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
126 ```ruby
4a2b77a @sbeckeriv [DOC] Added more consistent example of bulk importing documents into ind...
sbeckeriv authored
127 Tire.index 'articles' do
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
128 import articles do |documents|
129
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
130 documents.each { |document| document[:title].capitalize! }
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
131 end
4a2b77a @sbeckeriv [DOC] Added more consistent example of bulk importing documents into ind...
sbeckeriv authored
132
133 refresh
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
134 end
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
135 ```
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
136
a132a01 @karmi [DOC] Added info about how to get rid of DSL for using Tire, if that's y...
karmi authored
137 If this _declarative_ notation does not fit well in your context,
138 you can use _Tire's_ classes directly, in a more imperative manner:
139
140 ```ruby
141 index = Tire::Index.new('oldskool')
142 index.delete
143 index.create
144 index.store :title => "Let's do it the old way!"
145 index.refresh
146 ```
147
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
148 OK. Now, let's go search all the data.
5b01d11 @karmi Added README
karmi authored
149
c993ce2 @karmi [DOC] Updated README
karmi authored
150 We will be searching for articles whose `title` begins with letter “T”, sorted by `title` in `descending` order,
6da9265 @karmi [DOC] Updating the README; removing bullshit, better wording of features...
karmi authored
151 filtering them for ones tagged “ruby”, and also retrieving some [_facets_](http://www.elasticsearch.org/guide/reference/api/search/facets/)
5b01d11 @karmi Added README
karmi authored
152 from the database:
153
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
154 ```ruby
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
155 s = Tire.search 'articles' do
5b01d11 @karmi Added README
karmi authored
156 query do
aab2a85 @karmi Added the ability to specify *filters* for the query
karmi authored
157 string 'title:T*'
5b01d11 @karmi Added README
karmi authored
158 end
159
aab2a85 @karmi Added the ability to specify *filters* for the query
karmi authored
160 filter :terms, :tags => ['ruby']
161
2d283de @karmi [DOC] Fixed deprecated form of sorting in Readme
karmi authored
162 sort { by :title, 'desc' }
5b01d11 @karmi Added README
karmi authored
163
164 facet 'global-tags' do
165 terms :tags, :global => true
166 end
167
168 facet 'current-tags' do
169 terms :tags
170 end
171 end
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
172 ```
5b01d11 @karmi Added README
karmi authored
173
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
174 (Of course, we may also page the results with `from` and `size` query options, retrieve only specific fields
175 or highlight content matching our query, etc.)
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
176
5b01d11 @karmi Added README
karmi authored
177 Let's display the results:
178
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
179 ```ruby
5b01d11 @karmi Added README
karmi authored
180 s.results.each do |document|
aab2a85 @karmi Added the ability to specify *filters* for the query
karmi authored
181 puts "* #{ document.title } [tags: #{document.tags.join(', ')}]"
5b01d11 @karmi Added README
karmi authored
182 end
183
aab2a85 @karmi Added the ability to specify *filters* for the query
karmi authored
184 # * Two [tags: ruby, python]
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
185 ```
5b01d11 @karmi Added README
karmi authored
186
aab2a85 @karmi Added the ability to specify *filters* for the query
karmi authored
187 Let's display the global facets (distribution of tags across the whole database):
5b01d11 @karmi Added README
karmi authored
188
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
189 ```ruby
5b01d11 @karmi Added README
karmi authored
190 s.results.facets['global-tags']['terms'].each do |f|
191 puts "#{f['term'].ljust(10)} #{f['count']}"
192 end
193
194 # ruby 3
195 # python 1
196 # php 1
197 # java 1
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
198 ```
aab2a85 @karmi Added the ability to specify *filters* for the query
karmi authored
199
200 Now, let's display the facets based on current query (notice that count for articles
201 tagged with 'java' is included, even though it's not returned by our query;
202 count for articles tagged 'php' is excluded, since they don't match the current query):
203
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
204 ```ruby
aab2a85 @karmi Added the ability to specify *filters* for the query
karmi authored
205 s.results.facets['current-tags']['terms'].each do |f|
206 puts "#{f['term'].ljust(10)} #{f['count']}"
207 end
208
209 # ruby 1
210 # python 1
211 # java 1
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
212 ```
aab2a85 @karmi Added the ability to specify *filters* for the query
karmi authored
213
dea722b @karmi [DOC] Readme updates
karmi authored
214 Notice, that only variables from the enclosing scope are accessible.
a81b4bb @karmi Added information about different DSL syntax for blocks with argument (f...
karmi authored
215 If we want to access the variables or methods from outer scope,
216 we have to use a slight variation of the DSL, by passing the
217 `search` and `query` objects around.
218
219 ```ruby
220 @query = 'title:T*'
221
222 Tire.search 'articles' do |search|
223 search.query do |query|
224 query.string @query
225 end
226 end
227 ```
228
494de5c @karmi Added information about `boolean` queries into the Readme and tire-dsl.r...
karmi authored
229 Quite often, we need complex queries with boolean logic.
230 Instead of composing long query strings such as `tags:ruby OR tags:java AND NOT tags:python`,
231 we can use the [_bool_](http://www.elasticsearch.org/guide/reference/query-dsl/bool-query.html)
232 query. In _Tire_, we build them declaratively.
233
234 ```ruby
fdf0415 @karmi [DOC] Added information about passing options such as `use_dis_max` to q...
karmi authored
235 Tire.search 'articles' do
494de5c @karmi Added information about `boolean` queries into the Readme and tire-dsl.r...
karmi authored
236 query do
237 boolean do
238 should { string 'tags:ruby' }
239 should { string 'tags:java' }
240 must_not { string 'tags:python' }
241 end
242 end
243 end
244 ```
245
246 The best thing about `boolean` queries is that we can easily save these partial queries as Ruby blocks,
247 to mix and reuse them later. So, we may define a query for the _tags_ property:
248
249 ```ruby
250 tags_query = lambda do
251 boolean.should { string 'tags:ruby' }
252 boolean.should { string 'tags:java' }
253 end
254 ```
255
256 And a query for the _published_on_ property:
257
258 ```ruby
259 published_on_query = lambda do
260 boolean.must { string 'published_on:[2011-01-01 TO 2011-01-02]' }
261 end
262 ```
263
264 Now, we can combine these queries for different searches:
265
266 ```ruby
fdf0415 @karmi [DOC] Added information about passing options such as `use_dis_max` to q...
karmi authored
267 Tire.search 'articles' do
494de5c @karmi Added information about `boolean` queries into the Readme and tire-dsl.r...
karmi authored
268 query do
269 boolean &tags_query
270 boolean &published_on_query
271 end
272 end
273 ```
274
fdf0415 @karmi [DOC] Added information about passing options such as `use_dis_max` to q...
karmi authored
275 Note, that you can pass options for configuring queries, facets, etc. by passing a Hash as the last argument to the method call:
276
277 ```ruby
278 Tire.search 'articles' do
279 query do
280 string 'ruby python', :default_operator => 'AND', :use_dis_max => true
281 end
282 end
283 ```
284
0b65457 @karmi [REFACTOR] Added documentation and cleaning up tests for the lazy loadin...
karmi authored
285 You don't have to define the search criteria in one monolithic _Ruby_ block -- you can build the search step by step,
286 until you call the `results` method:
287
288 ```ruby
289 s = Tire.search('articles') { query { string 'title:T*' } }
290 s.filter :terms, :tags => ['ruby']
291 p s.results
292 ```
293
fdf0415 @karmi [DOC] Added information about passing options such as `use_dis_max` to q...
karmi authored
294 If configuring the search payload with blocks feels somehow too weak for you, you can pass
494de5c @karmi Added information about `boolean` queries into the Readme and tire-dsl.r...
karmi authored
295 a plain old Ruby `Hash` (or JSON string) with the query declaration to the `search` method:
5d7767f @karmi [DOC] Readme updates (cleanup, added info about dual interface for `Slin...
karmi authored
296
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
297 ```ruby
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
298 Tire.search 'articles', :query => { :fuzzy => { :title => 'Sour' } }
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
299 ```
5d7767f @karmi [DOC] Readme updates (cleanup, added info about dual interface for `Slin...
karmi authored
300
c993ce2 @karmi [DOC] Updated README
karmi authored
301 If this sounds like a great idea to you, you are probably able to write your application
302 using just `curl`, `sed` and `awk`.
5d7767f @karmi [DOC] Readme updates (cleanup, added info about dual interface for `Slin...
karmi authored
303
a132a01 @karmi [DOC] Added info about how to get rid of DSL for using Tire, if that's y...
karmi authored
304 Do note again, however, that you're not tied to the declarative block-style DSL _Tire_ offers to you.
0b65457 @karmi [REFACTOR] Added documentation and cleaning up tests for the lazy loadin...
karmi authored
305 If it makes more sense in your context, you can use the API directly, in a more imperative style:
a132a01 @karmi [DOC] Added info about how to get rid of DSL for using Tire, if that's y...
karmi authored
306
307 ```ruby
308 search = Tire::Search::Search.new('articles')
309 search.query { string('title:T*') }
310 search.filter :terms, :tags => ['ruby']
311 search.sort { by :title, 'desc' }
312 search.facet('global-tags') { terms :tags, :global => true }
313 # ...
0b65457 @karmi [REFACTOR] Added documentation and cleaning up tests for the lazy loadin...
karmi authored
314 p search.results
a132a01 @karmi [DOC] Added info about how to get rid of DSL for using Tire, if that's y...
karmi authored
315 ```
316
317 To debug the query we have laboriously set up like this,
318 we can display the full query JSON for close inspection:
5b01d11 @karmi Added README
karmi authored
319
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
320 ```ruby
5b01d11 @karmi Added README
karmi authored
321 puts s.to_json
aab2a85 @karmi Added the ability to specify *filters* for the query
karmi authored
322 # {"facets":{"current-tags":{"terms":{"field":"tags"}},"global-tags":{"global":true,"terms":{"field":"tags"}}},"query":{"query_string":{"query":"title:T*"}},"filter":{"terms":{"tags":["ruby"]}},"sort":[{"title":"desc"}]}
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
323 ```
9e4d593 @karmi Updating the README: fixing spelling, cleaning up the text, adding info ...
karmi authored
324
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
325 Or, better, we can display the corresponding `curl` command to recreate and debug the request in the terminal:
5b01d11 @karmi Added README
karmi authored
326
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
327 ```ruby
5b01d11 @karmi Added README
karmi authored
328 puts s.to_curl
aab2a85 @karmi Added the ability to specify *filters* for the query
karmi authored
329 # curl -X POST "http://localhost:9200/articles/_search?pretty=true" -d '{"facets":{"current-tags":{"terms":{"field":"tags"}},"global-tags":{"global":true,"terms":{"field":"tags"}}},"query":{"query_string":{"query":"title:T*"}},"filter":{"terms":{"tags":["ruby"]}},"sort":[{"title":"desc"}]}'
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
330 ```
5b01d11 @karmi Added README
karmi authored
331
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
332 However, we can simply log every search query (and other requests) in this `curl`-friendly format:
5d5f904 @karmi Updated the copy in README: adding infor about logger, highlight, cleani...
karmi authored
333
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
334 ```ruby
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
335 Tire.configure { logger 'elasticsearch.log' }
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
336 ```
5d5f904 @karmi Updated the copy in README: adding infor about logger, highlight, cleani...
karmi authored
337
5d7767f @karmi [DOC] Readme updates (cleanup, added info about dual interface for `Slin...
karmi authored
338 When you set the log level to _debug_:
339
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
340 ```ruby
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
341 Tire.configure { logger 'elasticsearch.log', :level => 'debug' }
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
342 ```
5d7767f @karmi [DOC] Readme updates (cleanup, added info about dual interface for `Slin...
karmi authored
343
344 the JSON responses are logged as well. This is not a great idea for production environment,
345 but it's priceless when you want to paste a complicated transaction to the mailing list or IRC channel.
346
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
347 The _Tire_ DSL tries hard to provide a strong Ruby-like API for the main _ElasticSearch_ features.
5b01d11 @karmi Added README
karmi authored
348
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
349 By default, _Tire_ wraps the results collection in a enumerable `Results::Collection` class,
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
350 and result items in a `Results::Item` class, which looks like a child of `Hash` and `Openstruct`,
10778f7 @karmi [DOC] Minor edits to documentation and Readme (update `sort` info; style...
karmi authored
351 for smooth iterating over and displaying the results.
5b01d11 @karmi Added README
karmi authored
352
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
353 You may wrap the result items in your own class by setting the `Tire.configuration.wrapper`
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
354 property. Your class must take a `Hash` of attributes on initialization.
5b01d11 @karmi Added README
karmi authored
355
10778f7 @karmi [DOC] Minor edits to documentation and Readme (update `sort` info; style...
karmi authored
356 If that seems like a great idea to you, there's a big chance you already have such class.
357
358 One would bet it's an `ActiveRecord` or `ActiveModel` class, containing model of your Rails application.
5b01d11 @karmi Added README
karmi authored
359
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
360 Fortunately, _Tire_ makes blending _ElasticSearch_ features into your models trivially possible.
5b01d11 @karmi Added README
karmi authored
361
1063687 @karmi Allow to set custom class as wrapper for result item (set in `Configurat...
karmi authored
362
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
363 ActiveModel Integration
364 -----------------------
365
ec476f3 @karmi [DOC] Updated the Readme (rails app template, callbacks are optional)
karmi authored
366 If you're the type with no time for lengthy introductions, you can generate a fully working
10778f7 @karmi [DOC] Minor edits to documentation and Readme (update `sort` info; style...
karmi authored
367 example Rails application, with an `ActiveRecord` model and a search form, to play with
368 (it even downloads _ElasticSearch_ itself, generates the application skeleton and leaves you with
369 a _Git_ repository to explore the steps and the code):
ec476f3 @karmi [DOC] Updated the Readme (rails app template, callbacks are optional)
karmi authored
370
fe7da17 [FIX] Added proper Github URL to Rails application template to README
Jakub Dušek authored
371 $ rails new searchapp -m https://raw.github.com/karmi/tire/master/examples/rails-application-template.rb
ec476f3 @karmi [DOC] Updated the Readme (rails app template, callbacks are optional)
karmi authored
372
bad6bc6 @karmi [DOC] Updated the Readme
karmi authored
373 For the rest of us, let's suppose you have an `Article` class in your _Rails_ application.
374
10778f7 @karmi [DOC] Minor edits to documentation and Readme (update `sort` info; style...
karmi authored
375 To make it searchable with _Tire_, just `include` it:
1063687 @karmi Allow to set custom class as wrapper for result item (set in `Configurat...
karmi authored
376
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
377 ```ruby
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
378 class Article < ActiveRecord::Base
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
379 include Tire::Model::Search
380 include Tire::Model::Callbacks
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
381 end
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
382 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
383
384 When you now save a record:
385
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
386 ```ruby
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
387 Article.create :title => "I Love ElasticSearch",
388 :content => "...",
389 :author => "Captain Nemo",
390 :published_on => Time.now
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
391 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
392
814e9c6 @redbeard Added the `Model::Search#index_prefix` setting for automatic adding of p...
redbeard authored
393 it is automatically added into an index called 'articles', because of the included callbacks.
ec476f3 @karmi [DOC] Updated the Readme (rails app template, callbacks are optional)
karmi authored
394
395 The document attributes are indexed exactly as when you call the `Article#to_json` method.
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
396
d5565b9 @karmi [DOC] README tweaks
karmi authored
397 Now you can search the records:
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
398
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
399 ```ruby
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
400 Article.search 'love'
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
401 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
402
10778f7 @karmi [DOC] Minor edits to documentation and Readme (update `sort` info; style...
karmi authored
403 OK. This is where the search game stops, often. Not here.
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
404
d5565b9 @karmi [DOC] README tweaks
karmi authored
405 First of all, you may use the full query DSL, as explained above, with filters, sorting,
406 advanced facet aggregation, highlighting, etc:
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
407
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
408 ```ruby
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
409 Article.search do
10778f7 @karmi [DOC] Minor edits to documentation and Readme (update `sort` info; style...
karmi authored
410 query { string 'love' }
411 facet('timeline') { date :published_on, :interval => 'month' }
412 sort { by :published_on, 'desc' }
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
413 end
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
414 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
415
bad6bc6 @karmi [DOC] Updated the Readme
karmi authored
416 Second, dynamic mapping is a godsend when you're prototyping.
bc32412 @karmi [ACTIVEMODEL] Added `MyModel.settings` method to allow creating the inde...
karmi authored
417 For serious usage, though, you'll definitely want to define a custom _mapping_ for your models:
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
418
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
419 ```ruby
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
420 class Article < ActiveRecord::Base
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
421 include Tire::Model::Search
422 include Tire::Model::Callbacks
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
423
424 mapping do
4e2466c @karmi [ACTIVEMODEL] Added documentation and more tests for the `:as` option
karmi authored
425 indexes :id, :index => :not_analyzed
426 indexes :title, :analyzer => 'snowball', :boost => 100
427 indexes :content, :analyzer => 'snowball'
428 indexes :content_size, :as => 'content.size'
429 indexes :author, :analyzer => 'keyword'
430 indexes :published_on, :type => 'date', :include_in_all => false
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
431 end
432 end
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
433 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
434
10778f7 @karmi [DOC] Minor edits to documentation and Readme (update `sort` info; style...
karmi authored
435 In this case, _only_ the defined model attributes are indexed. The `mapping` declaration creates the
bad6bc6 @karmi [DOC] Updated the Readme
karmi authored
436 index when the class is loaded or when the importing features are used, and _only_ when it does not yet exist.
bc32412 @karmi [ACTIVEMODEL] Added `MyModel.settings` method to allow creating the inde...
karmi authored
437
4e2466c @karmi [ACTIVEMODEL] Added documentation and more tests for the `:as` option
karmi authored
438 You can define different [_analyzers_](http://www.elasticsearch.org/guide/reference/index-modules/analysis/index.html),
439 [_boost_](http://www.elasticsearch.org/guide/reference/mapping/boost-field.html) levels for different properties,
440 or any other configuration for _elasticsearch_.
441
442 You're not limited to 1:1 mapping between your model properties and the serialized document. With the `:as` option,
443 you can pass a string or a _Proc_ object which is evaluated in the instance context (see the `content_size` property).
444
258218f @karmi [DOC] Fixed typo in the Readme, mapping != settings
karmi authored
445 Chances are, you want to declare also a custom _settings_ for the index, such as set the number of shards,
bc32412 @karmi [ACTIVEMODEL] Added `MyModel.settings` method to allow creating the inde...
karmi authored
446 replicas, or create elaborate analyzer chains, such as the hipster's choice: [_ngrams_](https://gist.github.com/1160430).
447 In this case, just wrap the `mapping` method in a `settings` one, passing it the settings as a Hash:
448
449 ```ruby
450 class URL < ActiveRecord::Base
451 include Tire::Model::Search
452 include Tire::Model::Callbacks
453
454 settings :number_of_shards => 1,
455 :number_of_replicas => 1,
456 :analysis => {
457 :filter => {
458 :url_ngram => {
459 "type" => "nGram",
460 "max_gram" => 5,
461 "min_gram" => 3 }
462 },
463 :analyzer => {
464 :url_analyzer => {
465 "tokenizer" => "lowercase",
466 "filter" => ["stop", "url_ngram"],
467 "type" => "custom" }
468 }
469 } do
470 mapping { indexes :url, :type => 'string', :analyzer => "url_analyzer" }
471 end
472 end
473 ```
474
475 It may well be reasonable to wrap the index creation logic declared with `Tire.index('urls').create`
1f8b594 @karmi [DOC] Added info about customized indexing logic
karmi authored
476 in a class method of your model, in a module method, etc, to have better control on index creation when
477 bootstrapping the application with Rake tasks or when setting up the test suite.
bc32412 @karmi [ACTIVEMODEL] Added `MyModel.settings` method to allow creating the inde...
karmi authored
478 _Tire_ will not hold that against you.
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
479
1255bfc @karmi [ACTIVEMODEL] Implemented all Tire features for models via a `MyModel.ti...
karmi authored
480 You may have just stopped wondering: what if I have my own `settings` class method defined?
481 Or what if some other gem defines `settings`, or some other _Tire_ method, such as `update_index`?
482 Things will break, right? No, they won't.
483
484 In fact, all this time you've been using only _proxies_ to the real _Tire_ methods, which live in the `tire`
485 class and instance methods of your model. Only when not trampling on someone's foot — which is the majority
486 of cases —, will _Tire_ bring its methods to the namespace of your class.
487
488 So, instead of writing `Article.search`, you could write `Article.tire.search`, and instead of
489 `@article.update_index` you could write `@article.tire.update_index`, to be on the safe side.
490 Let's have a look on an example with the `mapping` method:
491
492 ```ruby
493 class Article < ActiveRecord::Base
494 include Tire::Model::Search
495 include Tire::Model::Callbacks
496
497 tire.mapping do
498 indexes :id, :type => 'string', :index => :not_analyzed
499 # ...
500 end
501 end
502 ```
503
504 Of course, you could also use the block form:
505
506 ```ruby
507 class Article < ActiveRecord::Base
508 include Tire::Model::Search
509 include Tire::Model::Callbacks
510
511 tire do
512 mapping do
513 indexes :id, :type => 'string', :index => :not_analyzed
514 # ...
515 end
516 end
517 end
518 ```
519
520 Internally, _Tire_ uses these proxy methods exclusively. When you run into issues,
521 use the proxied method, eg. `Article.tire.mapping`, directly.
522
10778f7 @karmi [DOC] Minor edits to documentation and Readme (update `sort` info; style...
karmi authored
523 When you want a tight grip on how the attributes are added to the index, just
86b3c2f @karmi [DOC] Added more thorough instructions on how to use `to_indexed_json`
karmi authored
524 implement the `to_indexed_json` method in your model.
525
526 The easiest way is to customize the `to_json` serialization support of your model:
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
527
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
528 ```ruby
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
529 class Article < ActiveRecord::Base
86b3c2f @karmi [DOC] Added more thorough instructions on how to use `to_indexed_json`
karmi authored
530 # ...
531
532 include_root_in_json = false
533 def to_indexed_json
534 to_json :except => ['updated_at'], :methods => ['length']
535 end
536 end
537 ```
538
539 Of course, it may well be reasonable to define the indexed JSON from the ground up:
540
541 ```ruby
542 class Article < ActiveRecord::Base
543 # ...
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
544
545 def to_indexed_json
546 names = author.split(/\W/)
547 last_name = names.pop
548 first_name = names.join
549
550 {
551 :title => title,
552 :content => content,
553 :author => {
554 :first_name => first_name,
555 :last_name => last_name
556 }
557 }.to_json
558 end
559 end
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
560 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
561
1f8b594 @karmi [DOC] Added info about customized indexing logic
karmi authored
562 Notice, that you may want to skip including the `Tire::Model::Callbacks` module in special cases,
563 like when your records are indexed via some external mechanism, let's say a _CouchDB_ or _RabbitMQ_
564 [river](http://www.elasticsearch.org/blog/2010/09/28/the_river.html), or when you need better
565 control on how the documents are added to or removed from the index:
566
567 ```ruby
568 class Article < ActiveRecord::Base
569 include Tire::Model::Search
570
571 after_save do
572 update_index if state == 'published'
573 end
574 end
575 ```
576
1aa9561 @karmi [DOC] Added the information on new ActiveRecord integration to the Readm...
karmi authored
577 The results returned by `Article.search` are wrapped in the aforementioned `Item` class, by default.
578 This way, we have a fast and flexible access to the properties returned from _ElasticSearch_ (via the
579 `_source` or `fields` JSON properties). This way, we can index whatever JSON we like in _ElasticSearch_,
580 and retrieve it, simply, via the dot notation:
581
582 ```ruby
583 articles = Article.search 'love'
584 articles.each do |article|
585 puts article.title
586 puts article.author.last_name
587 end
588 ```
589
bad6bc6 @karmi [DOC] Updated the Readme
karmi authored
590 The `Item` instances masquerade themselves as instances of your model within a _Rails_ application
2cfdd48 @karmi [DOC] Added the documentation on eager loading results from the database...
karmi authored
591 (based on the `_type` property retrieved from _ElasticSearch_), so you can use them carefree;
1aa9561 @karmi [DOC] Added the information on new ActiveRecord integration to the Readm...
karmi authored
592 all the `url_for` or `dom_id` helpers work as expected.
593
2cfdd48 @karmi [DOC] Added the documentation on eager loading results from the database...
karmi authored
594 If you need to access the “real” model (eg. to access its assocations or methods not
1aa9561 @karmi [DOC] Added the information on new ActiveRecord integration to the Readm...
karmi authored
595 stored in _ElasticSearch_), just load it from the database:
596
597 ```ruby
598 puts article.load(:include => 'comments').comments.size
599 ```
bad6bc6 @karmi [DOC] Updated the Readme
karmi authored
600
2cfdd48 @karmi [DOC] Added the documentation on eager loading results from the database...
karmi authored
601 You can see that _Tire_ stays as far from the database as possible. That's because it believes
602 you have most of the data you want to display stored in _ElasticSearch_. When you need
bad6bc6 @karmi [DOC] Updated the Readme
karmi authored
603 to eagerly load the records from the database itself, for whatever reason,
604 you can do it with the `:load` option when searching:
2cfdd48 @karmi [DOC] Added the documentation on eager loading results from the database...
karmi authored
605
606 ```ruby
607 # Will call `Article.search [1, 2, 3]`
608 Article.search 'love', :load => true
609 ```
610
611 Instead of simple `true`, you can pass any options for the model's find method:
612
613 ```ruby
614 # Will call `Article.search [1, 2, 3], :include => 'comments'`
615 Article.search :load => { :include => 'comments' } do
616 query { string 'love' }
617 end
618 ```
619
1aa9561 @karmi [DOC] Added the information on new ActiveRecord integration to the Readm...
karmi authored
620 Note that _Tire_ search results are fully compatible with [`will_paginate`](https://github.com/mislav/will_paginate),
621 so you can pass all the usual parameters to the `search` method in the controller:
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
622
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
623 ```ruby
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
624 @articles = Article.search params[:q], :page => (params[:page] || 1)
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
625 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
626
1aa9561 @karmi [DOC] Added the information on new ActiveRecord integration to the Readm...
karmi authored
627 OK. Chances are, you have lots of records stored in your database. How will you get them to _ElasticSearch_? Easy:
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
628
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
629 ```ruby
1255bfc @karmi [ACTIVEMODEL] Implemented all Tire features for models via a `MyModel.ti...
karmi authored
630 Article.index.import Article.all
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
631 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
632
1aa9561 @karmi [DOC] Added the information on new ActiveRecord integration to the Readm...
karmi authored
633 This way, however, all your records are loaded into memory, serialized into JSON,
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
634 and sent down the wire to _ElasticSearch_. Not practical, you say? You're right.
635
10778f7 @karmi [DOC] Minor edits to documentation and Readme (update `sort` info; style...
karmi authored
636 Provided your model implements some sort of _pagination_ — and it probably does —, you can just run:
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
637
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
638 ```ruby
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
639 Article.import
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
640 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
641
642 In this case, the `Article.paginate` method is called, and your records are sent to the index
643 in chunks of 1000. If that number doesn't suit you, just provide a better one:
644
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
645 ```ruby
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
646 Article.import :per_page => 100
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
647 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
648
649 Any other parameters you provide to the `import` method are passed down to the `paginate` method.
650
651 Are we saying you have to fiddle with this thing in a `rails console` or silly Ruby scripts? No.
652 Just call the included _Rake_ task on the commandline:
653
9c46e2f @karmi [DOC] Added Github's colorization for bash snippets
karmi authored
654 ```bash
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
655 $ rake environment tire:import CLASS='Article'
9c46e2f @karmi [DOC] Added Github's colorization for bash snippets
karmi authored
656 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
657
658 You can also force-import the data by deleting the index first (and creating it with mapping
659 provided by the `mapping` block in your model):
660
9c46e2f @karmi [DOC] Added Github's colorization for bash snippets
karmi authored
661 ```bash
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
662 $ rake environment tire:import CLASS='Article' FORCE=true
9c46e2f @karmi [DOC] Added Github's colorization for bash snippets
karmi authored
663 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
664
665 When you'll spend more time with _ElasticSearch_, you'll notice how
666 [index aliases](http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases.html)
667 are the best idea since the invention of inverted index.
bad6bc6 @karmi [DOC] Updated the Readme
karmi authored
668 You can index your data into a fresh index (and possibly update an alias once everything's fine):
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
669
9c46e2f @karmi [DOC] Added Github's colorization for bash snippets
karmi authored
670 ```bash
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
671 $ rake environment tire:import CLASS='Article' INDEX='articles-2011-05'
9c46e2f @karmi [DOC] Added Github's colorization for bash snippets
karmi authored
672 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
673
674 OK. All this time we have been talking about `ActiveRecord` models, since
10778f7 @karmi [DOC] Minor edits to documentation and Readme (update `sort` info; style...
karmi authored
675 it is a reasonable _Rails_' default for the storage layer.
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
676
677 But what if you use another database such as [MongoDB](http://www.mongodb.org/),
678 another object mapping library, such as [Mongoid](http://mongoid.org/)?
679
680 Well, things stay mostly the same:
681
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
682 ```ruby
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
683 class Article
684 include Mongoid::Document
685 field :title, :type => String
686 field :content, :type => String
687
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
688 include Tire::Model::Search
689 include Tire::Model::Callbacks
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
690
91e39fb @karmi [ACTIVEMODEL] Added the support for casting model properties as Ruby obj...
karmi authored
691 # Let's use a different index name so stuff doesn't get mixed up.
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
692 #
693 index_name 'mongo-articles'
694
91e39fb @karmi [ACTIVEMODEL] Added the support for casting model properties as Ruby obj...
karmi authored
695 # These Mongo guys sure do get funky with their IDs in +serializable_hash+, let's fix it.
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
696 #
697 def to_indexed_json
698 self.to_json
699 end
700
701 end
702
703 Article.create :title => 'I Love ElasticSearch'
704
705 Article.search 'love'
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
706 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
707
bad6bc6 @karmi [DOC] Updated the Readme
karmi authored
708 _Tire_ does not care what's your primary data storage solution, if it has an _ActiveModel_-compatible
709 adapter. But there's more.
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
710
10778f7 @karmi [DOC] Minor edits to documentation and Readme (update `sort` info; style...
karmi authored
711 _Tire_ implements not only _searchable_ features, but also _persistence_ features. This means you can use a _Tire_ model **instead of your database**, not just for _searching_ your database. Why would you like to do that?
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
712
713 Well, because you're tired of database migrations and lots of hand-holding with your
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
714 database to store stuff like `{ :name => 'Tire', :tags => [ 'ruby', 'search' ] }`.
91e39fb @karmi [ACTIVEMODEL] Added the support for casting model properties as Ruby obj...
karmi authored
715 Because all you need, really, is to just dump a JSON-representation of your data into a database and load it back again.
d5565b9 @karmi [DOC] README tweaks
karmi authored
716 Because you've noticed that _searching_ your data is a much more effective way of retrieval
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
717 then constructing elaborate database query conditions.
91e39fb @karmi [ACTIVEMODEL] Added the support for casting model properties as Ruby obj...
karmi authored
718 Because you have _lots_ of data and want to use _ElasticSearch's_ advanced distributed features.
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
719
91e39fb @karmi [ACTIVEMODEL] Added the support for casting model properties as Ruby obj...
karmi authored
720 All good reasons to use _ElasticSearch_ as a schema-free and highly-scalable storage and retrieval/aggregation engine for your data.
721
722 To use the persistence mode, we'll include the `Tire::Persistence` module in our class and define its properties;
723 we can add the standard mapping declarations, set default values, or define casting for the property to create
724 lightweight associations between the models.
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
725
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
726 ```ruby
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
727 class Article
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
728 include Tire::Model::Persistence
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
729
730 validates_presence_of :title, :author
731
db6e911 @karmi [ACTIVEMODEL] Added support for property defaults in Tire::Model::Persis...
karmi authored
732 property :title, :analyzer => 'snowball'
733 property :published_on, :type => 'date'
734 property :tags, :default => [], :analyzer => 'keyword'
91e39fb @karmi [ACTIVEMODEL] Added the support for casting model properties as Ruby obj...
karmi authored
735 property :author, :class => Author
736 property :comments, :class => [Comment]
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
737 end
a601780 @karmi [DOC] Added Github syntax color flavour to README
karmi authored
738 ```
c8503a1 @karmi [DOC] Added information & instructions about ActiveRecord/ActiveModel in...
karmi authored
739
1aa9561 @karmi [DOC] Added the information on new ActiveRecord integration to the Readm...
karmi authored
740 Please be sure to peruse the [integration test suite](https://github.com/karmi/tire/tree/master/test/integration)
741 for examples of the API and _ActiveModel_ integration usage.
742
d68fb93 @kristianmandrup small README note on running test suite
authored
743 Running test suite
744 ------------------------
745
746 ```text
747 $ bundle
748 $ bundle exec rake
749 ```
0f6a99c @karmi [DOC] Added information about the `tire-contrib` project
karmi authored
750
751 Extensions and Additions
752 ------------------------
753
754 The [_tire-contrib_](http://github.com/karmi/tire-contrib/) project contains additions
987df34 @karmi [DOC] README updates
karmi authored
755 and extensions to the core _Tire_ functionality — be sure to check them out.
489ab53 @karmi Adding link to other libraries and clients
karmi authored
756
82cd413 @karmi [DOC] Heavy update of the README file: added docs about new features, ad...
karmi authored
757
489ab53 @karmi Adding link to other libraries and clients
karmi authored
758 Other Clients
759 -------------
760
761 Check out [other _ElasticSearch_ clients](http://www.elasticsearch.org/guide/appendix/clients.html).
762
763
5b01d11 @karmi Added README
karmi authored
764 Feedback
765 --------
766
19e570b @karmi [GEM] Updated gem name to "tire" and renamed all files from "slingshot" ...
karmi authored
767 You can send feedback via [e-mail](mailto:karmi@karmi.cz) or via [Github Issues](https://github.com/karmi/tire/issues).
5b01d11 @karmi Added README
karmi authored
768
769 -----
770
c8ecf20 @karmi [DOC] Added link to list of contributors to the Readme
karmi authored
771 [Karel Minarik](http://karmi.cz) and [contributors](http://github.com/karmi/tire/contributors)
Something went wrong with that request. Please try again.