Hayfork
Full-Text search for ActiveRecord and Postgres.
Hayfork generates triggers to maintain a Haystack of all searchable fields that Postgres can index easily and efficiently.
About
How Hayfork works
You define the tables and fields that are to be searchable. Hayfork defines triggers that watch those tables for INSERTs, UPDATEs, and DELETEs. In response, the triggers insert, update, or delete corresponding rows in the haystack: one row per searchable field.
They Haystack has a column named search_vector
that can be indexed, optimizing searches.
A query against the Haystack returns a list of hits — one result may have more than one hit (as when a search string is found in both the text and title of a book).
Why Hayfork?
Hayfork is designed to:
- optimize searches by:
- executing one query to search any number of fields or tables
- writing
search_vector
when hits are inserted so that the column may be indexed
- rebuild the haystack at the database level so that it works with bulk-inserted records
- support extension so, by adding metadata to a hit, you can:
- provide additional context about a result in the UI
- search only within a particular field (e.g. enable users to search
author:Potok
to find books whether the author's name includes "Potok") - scope searches by a user or tenant or feature
Setup
Generate a haystack table and model for your application.
$ rails generate hayfork:haystack
This will generate several files:
-
app/models/haystack.rb
anddb/migrate/000_create_haystack.rb
define the Haystack -
app/models/query.rb
(and several models in theQuery
namespace) are responsible for parsing a query string and constructing the SQL to execute it. -
lib/haystack_triggers.rb
is where you will define the tables and fields to be added to the Haystack.
lib/haystack_triggers.rb
Basic Example
This basic example allows you to search all your employees and projects with one search box:
Hayfork.maintain(Haystack) do
foreach(Employee) do
insert(:full_name)
end
foreach(Project) do
insert(:title)
end
end
Multiple Fields
To allow finding employees by multiple traits (e.g by name, job title, or short biography), you can define multiple insert
statements per employee:
Hayfork.maintain(Haystack) do
foreach(Employee) do
insert(:full_name)
insert(:position)
insert(:short_bio)
end
end
Scoping Searches
Additional columns on haystack
can also be useful for scoping searches. Suppose we're maintaining a database of employees for multiple companies. We would want to scope searches by company. If we've added company_id
to our haystack, we can populate it like this:
Hayfork.maintain(Haystack) do
foreach(Employee) do
set :company_id, row[:company_id]
insert(:full_name)
insert(:position)
insert(:short_bio)
end
end
In this line,
set :company_id, row[:company_id]
-
row
is an instance ofArel::Table
that represents the row passed to the trigger;row
is present in everyforeach
block. -
set
assigns a value that will be inserted in the haystack for all followinginsert
statements.
belongs_to
If a book belongs_to :author
, you can find the book by either its title or its author's name like this:
Hayfork.maintain(Haystack) do
foreach(Book) do
insert(:title)
insert(author: :name)
end
end
When a book is inserted, this will add an entry to the haystack for the book's title and another entry for its author's name. If book.author_id
is changed, it'll replace the appropriate entry in the haystack; but what if authors.name
is modified? We also need to watch the authors
table for changes to modify the haystack:
Hayfork.maintain(Haystack) do
foreach(Book) do
insert(:title)
insert(author: :name)
end
foreach(Author) do
joins :books
set :search_result_type, "Book"
set :search_result_id, Book.arel_table[:id]
insert(:name)
end
end
In the examples seen before, we haven't set search_result_type
and search_result_id
. If these values aren't defined, Hayfork assumes that the model passed to foreach
— the table being watched — is the search result; but for an associated record, we need to explicitly declare the result. In this case, an entry is added to the haystack for every book that belongs to an author.
has_many
has_many
and has_many :through
associations work much the same way. If an article has_many :comments
, you can find an article by any of its comments like this:
Hayfork.maintain(Haystack) do
foreach(Article) do
insert(comments: :text)
end
foreach(Comment) do
joins :article
set :search_result_type, "Article"
set :search_result_id, Article.arel_table[:id]
insert(:text)
end
end
Rebuild Triggers
After making changes to lib/haystack_triggers.rb
or to the default scopes of any of the models being used by the Triggers File, you'll need to replace the triggers in your database and rebuild the Haystack. Hayfork generates a migration to do that:
$ rails generate hayfork:rebuild
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake test
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/boblail/hayfork.
License
The gem is available as open source under the terms of the MIT License.