Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 172 lines (114 sloc) 5.379 kB
50b955f @nertzy Add the beginnings of a README
nertzy authored
1 = pg_search
2
3 * http://github.com/casecommons/pg_search/
4
5 == DESCRIPTION:
6
7 PgSearch builds named scopes that take advantage of PostgreSQL's full text search
8
9 == INSTALL:
10
11 gem install pg_search
12
13 === Rails 3
14
15 In Gemfile
16
17 gem 'pg_search'
18
19 === Rails 2
20
21 In environment.rb
22
23 config.gem 'pg_search'
24
25 In Rakefile
26
27 require 'rubygems'
28 require 'pg_search/tasks'
29
0511156 Adding more documentation
Grant Hutchins & Rachel Heaton authored
30 == USAGE
31
32 To add PgSearch to an ActiveRecord model, simply include the PgSearch module.
33
34 class Shape < ActiveRecord::Base
35 include PgSearch
36 end
37
38 === pg_search_scope
39
40 You can use pg_search_scope to build a search scope. The first parameter is a scope name, and the second parameter is an options hash. The only required option is :against, which tells pg_search_scope which column or columns to search against.
41
42 ==== Searching against one column
43
44 To search against a column, pass a symbol as the :against option.
45
46 class BlogPost < ActiveRecord::Base
47 include PgSearch
48 pg_search_scope :search_by_title, :against => :title
49 end
50
51 We now have an ActiveRecord scope named search_by_title on our BlogPost model. It takes one parameter, a search query string.
52
53 BlogPost.create!(:title => "Recent Developments in the World of Pastrami")
54 BlogPost.create!(:title => "Prosciutto and You: A Retrospective")
55 BlogPost.search_by_title("pastrami") # => [#<BlogPost id: 2, title: "Recent Developments in the World of Pastrami">]
56
57 ==== Searching against multiple columns
58
59 Just pass an Array if you'd like to search more than one column.
60
61 class Person < ActiveRecord::Base
62 include PgSearch
63 pg_search_scope :search_by_full_name, :against => [:first_name, :last_name]
64 end
65
66 Now our search query can match either or both of the columns.
67
68 person_1 = Person.create!(:first_name => "Grant", :last_name => "Hill")
69 person_2 = Person.create!(:first_name => "Hugh", :last_name => "Grant")
70
71 Person.search_by_full_name("Grant") # => [person_1, person_2]
72 Person.search_by_full_name("Grant Hill") # => [person_1]
73
74 ==== Searching through associations
75
76 You can pass a Hash into the :associated_against option to search columns on other models. The keys are the names of the associations and the value works just like an :against option for the other model.
77
78 class Cracker < ActiveRecord::Base
79 end
80
81 class Cheese < ActiveRecord::Base
82 has_many :cheeses
83 end
84
85 class Salami < ActiveRecord::Base
86 include PgSearch
87
88 belongs_to :cracker
89 has_many :cheeses, :through => :cracker
90
91 pg_search_scope :tasty_search, :associated_against => {
92 :cheeses => [:kind, :brand],
93 :cracker => :kind
94 }
95 end
96
97 salami_1 = Salami.create!
98 salami_2 = Salami.create!
99 salami_3 = Salami.create!
100
101 limburger = Cheese.create!(:kind => "Limburger")
102 brie = Cheese.create!(:kind => "Brie")
103 pepper_jack = Cheese.create!(:kind => "Pepper Jack")
104
105 Cracker.create!(:kind => "Black Pepper", :cheeses => [brie], :salami => salami_1)
106 Cracker.create!(:kind => "Ritz", :cheeses => [limburger, pepper_jack], :salami => salami_2)
107 Cracker.create!(:kind => "Graham", :cheeses => [limburger], :salami => salami_3)
108
109 Salami.tasty_search("pepper") # => [salami_1, salami_2]
110
111 === Searching using different search features
112
113 By default, pg_search_scope uses the built-in {PostgreSQL text search}[link:http://www.postgresql.org/docs/current/static/textsearch-intro.html]. If you pass the :features option to pg_search_scope, you can choose alternative search techniques.
114
115 class Beer < ActiveRecord::Base
116 include PgSearch
117 pg_search_scope :against => :name, :features => [:tsearch, :trigram, :dmetaphone]
118 end
119
120 The currently implemented features are
121
122 * :tsearch - {Full text search}[link:http://www.postgresql.org/docs/current/static/textsearch-intro.html] (built-in with 8.3 and later, available as a contrib package for some earlier versions)
123 * :trigram - {Trigram search}[link:http://www.postgresql.org/docs/current/static/pgtrgm.html], which requires the trigram contrib package
124 * :dmetaphone - {Double Metaphone search}[link:http://www.postgresql.org/docs/9.0/static/fuzzystrmatch.html#AEN120188], which requires the fuzzystrmatch contrib package
125
126 ==== :tsearch (Full Text Search)
127
128 PostgreSQL's built-in full text search supports weighting, prefix searches, and stemming in multiple languages.
129
130 ===== Weighting
131 Each searchable column can be given a weight of "A", "B", "C", or "D". Columns with earlier letters are weighted higher than those with later letters. So, in the following example, the title is the most important, followed by the subtitle, and finally the content.
132
133 class NewsArticle < ActiveRecord::Base
134 include PgSearch
135 pg_search_scope :against => {
136 :title => 'A',
137 :subtitle => 'B',
138 :content => 'C'
139 }
140 end
141
142 You can also pass the weights in as an array of arrays, or any other structure that responds to #each and yields either a single symbol or a symbol and a weight. If you omit the weight, a default will be used.
143
144 class NewsArticle < ActiveRecord::Base
145 include PgSearch
146 pg_search_scope :against => [
147 [:title, 'A'],
148 [:subtitle, 'B'],
149 [:content, 'C']
150 ]
151 end
152
153 class NewsArticle < ActiveRecord::Base
154 include PgSearch
155 pg_search_scope :against => [
156 [:title, 'A'],
157 {:subtitle => 'B'},
158 :content
159 ]
160 end
161
162
50b955f @nertzy Add the beginnings of a README
nertzy authored
163 == REQUIREMENTS
164
165 * ActiveRecord 2 or 3
166 * Postgresql
167 * Postgresql contrib modules for certain features
168
169 == LICENSE:
170
0511156 Adding more documentation
Grant Hutchins & Rachel Heaton authored
171 MIT
Something went wrong with that request. Please try again.