Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 149 lines (85 sloc) 5.985 kb
d0769a4 @ryanb adding readme and license
authored
1 = Xapit
2
da05373 @ryanb releasing version 0.3.0
authored
3 Xapit (pronounced "zap it") is a Ruby gem for doing full text searching through {Xapian}[http://xapian.org/]. This project was recently rewritten and is not yet ready for production. Please try it out and let me know if there are any issues.
d0769a4 @ryanb adding readme and license
authored
4
5
6 == Install
7
bd8551f @ryanb updating readme for 0.3 differences
authored
8 First, install Xapian with the Ruby bindings. The easiest way is through {Homebrew}[http://mxcl.github.com/homebrew/].
d0271ae @ryanb updating readme and todo list
authored
9
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
10 brew install xapian --ruby
d0271ae @ryanb updating readme and todo list
authored
11
bd8551f @ryanb updating readme for 0.3 differences
authored
12 Note: this is tied to the current version of Ruby you have installed. If you use RVM be certain you're in the correct version. See {Installing Xapian}[https://github.com/ryanb/xapit/wiki/Xapian-Installation] for other methods.
b500d5b @ryanb adding gem installation instructions to readme
authored
13
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
14 Next add Xapit to your Gemfile and run the +bundle+ command.
4959550 @ryanb removing unused whitespace
authored
15
da05373 @ryanb releasing version 0.3.0
authored
16 gem "xapit", "~> 0.3"
b500d5b @ryanb adding gem installation instructions to readme
authored
17
fd7f29d @ryanb some updates to readme
authored
18 Then if you are in a Rails application, run the installation generator.
b500d5b @ryanb adding gem installation instructions to readme
authored
19
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
20 rails g xapit:install
d0769a4 @ryanb adding readme and license
authored
21
bd8551f @ryanb updating readme for 0.3 differences
authored
22 This creates a {configuration file}[https://github.com/ryanb/xapit/wiki/Configuration] and a rackup file for production use.
23
d0769a4 @ryanb adding readme and license
authored
24
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
25 == Index
d0769a4 @ryanb adding readme and license
authored
26
fd7f29d @ryanb some updates to readme
authored
27 To make a model searchable you must define an index through the +xapit+ method. Here is an example of the four methods you can call there.
28ab81e @ryanb updating readme
authored
28
d0769a4 @ryanb adding readme and license
authored
29 class Article < ActiveRecord::Base
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
30 xapit do
31 text :name, :content
32 field :category_id
33 sortable :id, :created_at
34 facet :author_name, "Author"
d0769a4 @ryanb adding readme and license
authored
35 end
36 end
37
bd8551f @ryanb updating readme for 0.3 differences
authored
38 This indexes the model to be searched in a variety of ways (shown below). See the {Indexing}[https://github.com/ryanb/xapit/wiki/Indexing] wiki page for details.
d0271ae @ryanb updating readme and todo list
authored
39
fd7f29d @ryanb some updates to readme
authored
40 Currently only Active Record is supported, but expect support for other libraries soon.
41
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
42 The index will automatically be updated when records are added or removed. You can regenerate the index manually to fill it with any existing records.
d0769a4 @ryanb adding readme and license
authored
43
44 rake xapit:index
45
46
47 == Search
48
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
49 Use the +search+ class method to perform a full text search on the index. This returns a Xapit scope where additional scoping methods can be called similar to Active Record scopes.
4959550 @ryanb removing unused whitespace
authored
50
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
51 # simple full text search
d0769a4 @ryanb adding readme and license
authored
52 @articles = Article.search("phone")
4959550 @ryanb removing unused whitespace
authored
53
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
54 # full text search with basic boolean matching
94fb5c4 @ryanb switching default query parser to ClassicQueryParser
authored
55 @articles = Article.search("phone OR fax NOT email")
36a5c10 @ryanb adding documentation for boolean search query support
authored
56
e955276 @ryanb adding pagination support
authored
57 # pagination works with kaminari and will_paginate
b65910c @ryanb renaming per to per_page
authored
58 @articles = Article.search("phone").page(10).per_page(20)
d0769a4 @ryanb adding readme and license
authored
59
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
60 # search based on a specific field
61 @articles = Article.search("phone").where(:category_id => params[:category_id])
4883c0b @ryanb adding Xapit.search which is a generic search
authored
62
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
63 # search for multiple negative conditions (doesn't match 3, 5, or 8)
64 @articles = Article.search("phone").not_where(:category_id => [3, 5, 8])
d0769a4 @ryanb adding readme and license
authored
65
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
66 # search for range of conditions by number
67 @articles = Article.search.where(:released_at => 2.years.ago..Time.now)
b09a1ed @ryanb documentation clarifications and improvements
authored
68
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
69 # order based on sortable fields, sorting defaults to most relevant
d828479 @ryanb fixing order search clause in readme
authored
70 @articles = Article.search("phone").order(:created_at, :desc)
d0769a4 @ryanb adding readme and license
authored
71
72 Simply iterate through the returned set to display the results.
73
74 <% for article in @articles %>
75 <%= article.name %>
76 <% end %>
77
bd8551f @ryanb updating readme for 0.3 differences
authored
78 See the {Searching}[https://github.com/ryanb/xapit/wiki/Searching] wiki page for more details.
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
79
d0769a4 @ryanb adding readme and license
authored
80
8fc7d53 @ryanb adding documentation for spelling
authored
81 == Spelling
82
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
83 Spelling suggestions are available when there is a simlarly indexed term.
8fc7d53 @ryanb adding documentation for spelling
authored
84
85 <% if @articles.spelling_suggestion %>
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
86 Did you mean <%= link_to @articles.spelling_suggestion, :overwrite_params => { :keywords => @articles.spelling_suggestion } %>?
8fc7d53 @ryanb adding documentation for spelling
authored
87 <% end %>
88
bd8551f @ryanb updating readme for 0.3 differences
authored
89 Note: the spelling feature is disabled by default in the test environment because it uses an in-memory database.
90
8fc7d53 @ryanb adding documentation for spelling
authored
91
d0769a4 @ryanb adding readme and license
authored
92 == Facets
93
94 Facets allow you to further filter the result set based on certain attributes.
95
96 <% for facet in @articles.facets %>
97 <%= facet.name %>
98 <% for option in facet.options %>
0ea0a65 @ryanb removing unnecessary parenthesis in documentation
authored
99 <%= link_to option.name, :overwrite_params => { :facets => option } %>
d0769a4 @ryanb adding readme and license
authored
100 (<%= option.count %>)
101 <% end %>
102 <% end %>
103
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
104 The facet option is passed in through the URL which you can add to the search.
d0769a4 @ryanb adding readme and license
authored
105
8157abc @ryanb renaming match_facets to with_facets
authored
106 Article.search("phone").with_facets(params[:facets])
d0769a4 @ryanb adding readme and license
authored
107
6341047 @ryanb adding Xapit.index_all and updating readme
authored
108 You can also list the applied facets along with a remove link.
109
110 <% for option in @articles.applied_facet_options %>
b4ef7fe @ryanb fixing applied_facet_options
authored
111 <%= option.name %>
0ea0a65 @ryanb removing unnecessary parenthesis in documentation
authored
112 <%= link_to "remove", :overwrite_params => { :facets => option } %>
6341047 @ryanb adding Xapit.index_all and updating readme
authored
113 <% end %>
114
1fbe4ca @ryanb adding documentation for config settings in README
authored
115
116
bd8551f @ryanb updating readme for 0.3 differences
authored
117 == Testing
1fbe4ca @ryanb adding documentation for config settings in README
authored
118
bd8551f @ryanb updating readme for 0.3 differences
authored
119 To use Xapit in the test environment, you will need to reload the configuration before each test. For example, you can do this in RSpec:
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
120
bd8551f @ryanb updating readme for 0.3 differences
authored
121 config.before(:each) do
122 Xapit.reload
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
123 end
124
bd8551f @ryanb updating readme for 0.3 differences
authored
125 Xapit is also disabled by default in the test environment so you can enable it on a per-test basis. This way it doesn't slow down tests which don't need Xapit search.
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
126
bd8551f @ryanb updating readme for 0.3 differences
authored
127 Xapit.enable
128 # create records and test searching functionality
7e3c4c1 @ryanb updating readme to how I want 0.3 to work, not yet working this way
authored
129
9dfc7a0 @ryanb adding index method for indexing models
authored
130 If you have existing records in the database you want to search (maybe loaded by fixtures) you can index those.
d0769a4 @ryanb adding readme and license
authored
131
9dfc7a0 @ryanb adding index method for indexing models
authored
132 Xapit.index(Article, Comment) # or whatever models you need
d0769a4 @ryanb adding readme and license
authored
133
bd8551f @ryanb updating readme for 0.3 differences
authored
134 By default, the test environment keeps the Xapian database in memory which makes it much faster and easier to reset. The problem is that the spelling suggestion feature does not work with in-memory databases, so it is disabled in the test environment by default. All of this can be customized in the {configuration file}[https://github.com/ryanb/xapit/wiki/Configuration].
d0769a4 @ryanb adding readme and license
authored
135
a943392 @ryanb adding bug reporting note to readme linking to issue tracker
authored
136
bd8551f @ryanb updating readme for 0.3 differences
authored
137 == Production
a943392 @ryanb adding bug reporting note to readme linking to issue tracker
authored
138
bd8551f @ryanb updating readme for 0.3 differences
authored
139 The default Xapit setup works well in development because there is only one instance of the Rails app running. However in production you will need to move Xapit to a separate process so all of the instances can communicate to it. To do this, start up the rackup file provided. You will likely want to put this behind a server such as Passenger.
a943392 @ryanb adding bug reporting note to readme linking to issue tracker
authored
140
bd8551f @ryanb updating readme for 0.3 differences
authored
141 rackup xapit.ru
a943392 @ryanb adding bug reporting note to readme linking to issue tracker
authored
142
bd8551f @ryanb updating readme for 0.3 differences
authored
143 Now when you start up your Rails app in production it will use this server. You can configure the server URL in the {configuration file}[https://github.com/ryanb/xapit/wiki/Configuration].
d0769a4 @ryanb adding readme and license
authored
144
145
bd8551f @ryanb updating readme for 0.3 differences
authored
146 == Bug Reports
d0769a4 @ryanb adding readme and license
authored
147
fd7f29d @ryanb some updates to readme
authored
148 First check out the {troubleshooting section}[https://github.com/ryanb/xapit/wiki/Troubleshooting] when you have problems. If you have found a bug or have a feature to request, please add it to the {GitHub issue tracker}[https://github.com/ryanb/xapit/issues] if it is not there already. Feel free to treat it as a mailing list and discuss new ideas or bring up any confusion you may have.
Something went wrong with that request. Please try again.