pg_search

PgSearch provides two distinct searching techniques:

1. Multi-search: Mixes records from many different Active Record classes into a single global search index. This is ideal for implementing a site-wide generic search page.
2. Search Scopes: Allows for advanced searching restricted to a single Active Record class. This is best suited for features like autocompleters or faceted search filtering.

PgSearch automatically builds two associations:

1. On the original record: has_one :pg_search_document.
2. On the PgSearch::Document record: belongs_to :searchable (polymorphic).

odyssey = EpicPoem.create!(title: "Odyssey", author: "Homer")
search_document = odyssey.pg_search_document
search_document.searchable # => #<EpicPoem id: 1, ...>

odyssey = EpicPoem.create!(title: "Odyssey", author: "Homer")
search_document = odyssey.pg_search_document
search_document.searchable # => #<EpicPoem id: 1, title: "Odyssey", author: "Homer">

To speed up large bulk operations (like importing records from an external source), you can wrap the operation in a PgSearch.disable_multisearch block. This prevents indexing during the operation, allowing you to rebuild search documents offline later using more efficient methods.

PgSearch.disable_multisearch do
  Movie.import_from_xml_file(File.open("movies.xml"))
end

If you change :against options or if your index is out of sync (e.g., due to using update_all which skips callbacks), you must rebuild the documents.

Using Ruby

To delete and regenerate all documents for a specific class:

PgSearch::Multisearch.rebuild(Product)

Options for rebuild:

• clean_up: false: Prevents deleting existing records before regenerating.
• transactional: false: Runs the rebuild outside of a single transaction.

Using Rake

# Rebuild for a specific class
$ rake pg_search:multisearch:rebuild[BlogPost]

# Rebuild for a specific class in a specific PostgreSQL schema
$ rake pg_search:multisearch:rebuild[BlogPost,my_schema]

You can install pg_search by running the gem installation command or by adding it to your Gemfile.

Requirements

• Ruby 3.3+
• Active Record 7.2+
• PostgreSQL 9.2+
• Certain features may require specific PostgreSQL extensions.

To enable PgSearch functionality in an Active Record model, include the PgSearch::Model module within your class definition.

class Shape < ActiveRecord::Base
  include PgSearch::Model
end

Double Metaphone matches words that sound alike. This requires the PostgreSQL fuzzystrmatch extension and a specific utility function.

To set up the required database function, run:

$ rails g pg_search:migration:dmetaphone
$ rake db:migrate

class Word < ActiveRecord::Base
  include PgSearch::Model
  pg_search_scope :that_sounds_like,
                  against: :spelling,
                  using: :dmetaphone
end

# Example usage:
# Word.that_sounds_like("fir") # => [four, far, fur]

Before using the multi-search feature, you must generate and run a migration to create the pg_search_documents table.

$ rails g pg_search:migration:multisearch
$ rake db:migrate

You can set default options for all PgSearch.multisearch calls by configuring PgSearch.multisearch_options in an initializer. These options use the same syntax as pg_search_scope.

PgSearch.multisearch_options = {
  using: [:tsearch, :trigram],
  ignoring: :accents
}