Skip to content
A polymorphic, storage-system independent search engine for Ruby on Rails.
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.yardoc
lib
spec
.gitignore
.rspec
.travis.yml
Gemfile
Guardfile
MIT-LICENSE
README.md
Rakefile
pose.gemspec

README.md

POlymorphic SEarch Build status Code Climate Coverage Status Dependency Status

A database agnostic fulltext search engine for ActiveRecord objects. See also Pose Rails Adapter.

  • Searches over several classes at once.
  • The searchable content of each class and document can be freely customized.
  • Uses application database - no separate servers, databases, or search engines required.
  • Does not pollute the searchable classes nor their database tables.
  • Very fast search, doing only simple queries over fully indexed columns.
  • Allows to augment the fulltext search query with your own joins and where clauses.

Installation

Versions

  • 2.x for Rails 3.x compatibilty
  • 3.0 for Rails 4 compatibilty
  • 3.1 introduces a new setup. The pose gem is now a generic Ruby gem that works with any Ruby web server that uses ActiveRecord, like Sinatra, Padrino, or Rails. Generators for installation and uninstallation are extracted into the pose_rails gem.

Set up the gem.

Add the gem to your Gemfile and run bundle install

gem 'pose'

Create the database tables for pose.

$ rake pose:install

Pose creates two tables in your database. These tables are automatically populated and kept up to date.

  • pose_words: index of all the words that occur in the searchable content.
  • pose_assignments: lists which word occurs in which document.

Make your ActiveRecord models searchable

Each model defines the searchable content through the posify method. Valid parameters are

  • names of fields
  • names of methods
  • a block

The value/result of each parameter is added to the search index for this instance. Here are a few examples:

class User < ActiveRecord::Base
  # first_name and last_name are attributes

  # This line makes the class searchable.
  posify :first_name, :last_name, :address

  def address
    "#{street} #{city} #{state}"
  end
end
class MyClass < ActiveRecord::Base

  # This line makes the class searchable.
  posify do

    # Only active instances should show up in search results.
    return nil unless status == :active

    # The searchable content.
    [ self.foo,
      self.parent.bar,
      self.children.map &:name ].join ' '
  end
end

You can mix and match all parameter types for posify at will. Note that you can return whatever content you want in the posify block, not only data from this object, but also data from related objects, class names, etc.

Now that this class is posified, any create, update, or delete operation on any instance of this class will update the search index automatically.

Index existing records in your database

Data that existed in your database before adding Pose isn't automatically included in the search index. You have to index those records manually once. Future updates will happen automatically.

To index all entries of MyClass, run rake 'pose:reindex_all[MyClass]' on the command line.

At this point, you are all set up. Let's perform a search!

Upgrading from version 1.x

Version 2 is a proper Rails engine, and comes with a slightly different database table schema. Upgrading is as simple as

$ rails generate pose:upgrade
$ rake db:migrate

Searching

To search, simply call Pose's search method, and tell it the search query as well as in which classes it should search.

result = Pose.search 'foo', [MyClass, MyOtherClass]

This searches for all instances of MyClass and MyOtherClass that contain the word 'foo'. The method returns a hash that looks like this:

{
  MyClass => [ <myclass instance 1>, <myclass instance 2> ],
  MyOtherClass => [ ],
}

In this example, it found two results of type MyClass and no results of type MyOtherClass. A Pose search returns the object instances that match the query. This behavior, as well as many others, is configurable through search options.

Search options

Configure the searched classes

Pose accepts an array of classes to search over.

result = Pose.search 'search text', [MyClass, MyOtherClass]

When searching a single class, it can be provided directly, i.e. not as an array.

result = Pose.search 'foo', MyClass

Configure the result data

Search results are the instances of the objects matching the search query. If you want to just get the ids of the search results, and not the full instances, use the parameter :result_type.

# Returns ids instead of object instances.
result = Pose.search 'foo', MyClass, result_type: :ids

Limit the amount of search results

By default, Pose returns all matching items. To limit the result set, use the :limit search parameter.

# Returns only 20 search results.
result = Pose.search 'foo', MyClass, limit: 20

Combine fulltext search with structured data search

You can add your own ActiveRecord query clauses (JOINs and WHEREs) to a fulltext search operation. For example, given a class Note that belongs to a User class and has a boolean attribute public, finding all public notes from other users containing "foo" is as easy as:

result = Pose.search 'foo',
                     Note,
                     joins: Note,
                     where: [ ['notes.public = ?', true],
                              ['user_id <> ?', @current_user.id] ] ]

Combining ActiveRecord query clauses with fulltext search only works when searching over a single class.

Customize the SELECT clause with which results are loaded

This feature only makes sense if you load one result class. It allows to only read the given set of attributes from the database. The only use case for this is performance optimization.

result = Pose.search 'foo',
                     Note,
                     select: 'id, text'

This query returns all Notes that have 'foo' in their text, but loads only their id and text attributes from the database.

Maintenance

Besides an accasional search index cleanup, Pose is relatively maintenance free. The search index is automatically updated when objects are created, updated, or deleted.

Optimizing the search index

The search index keeps all the words that were ever used around. After deleting or changing a large number of objects, you can shrink the database storage consumption of Pose's search index by removing no longer used search terms from it.

$ rake pose:index:vacuum

Recreating the search index from scratch

To index existing data in your database, or after buld-loading data outside of ActiveRecord into your database, you should recreate the search index from scratch.

rake pose:index:reindex_all[MyClass]

Uninstalling

To remove all traces of Pose from your database, run:

rails generate pose:remove

Also don't forget to remove the posify block from your models as well as the pose gem from your Gemfile.

Use Pose in your tests

Pose can slow down your tests, because it updates the search index on every :create, :update, and :delete operation in the database. To avoid that in your not search-related tests, you can disable Pose in your test environments, and only enable it for the tests that actually need search functionality.

To disable Pose for tests, add this line to config/environments/test.rb

Pose::CONFIGURATION[:perform_search] = false

Now, with search disabled in the test environment, enable Pose in some of your tests by setting the same value to true inside the tests:

context 'with search enabled' do

  before :all do
    Pose::CONFIGURATION[:perform_search] = true
  end

  after :all do
    Pose::CONFIGURATION[:perform_search] = false
  end

  it 'has search enabled in this test here...'

  it 'has search enabled in this test as well...'
end

Development

If you find a bug, have a question, or a better idea, please open an issue on the Pose issue tracker. Or, clone the repository, make your changes, and submit a unit-tested pull request!

Run the unit tests for the Pose Gem

Pose can work with Sqlite3, Postgesql and MySQL by default. To run tests, please create database configuration file spec/support/config/database.yml, please refer to the template: spec/support/config/database.yml.example

Then run the tests.

bundle exec rake test

Road Map

  • pagination of search results
  • ordering
  • weighting search results
  • test Pose with more types of data stores (NoSQL, Google DataStore etc)
Something went wrong with that request. Please try again.