pg_search 2.1.2 → 2.3.6

data/README.md

@@ -1,25 +1,20 @@
 # [pg_search](http://github.com/Casecommons/pg_search/)
 
 [![Gem Version](https://img.shields.io/gem/v/pg_search.svg?style=flat)](https://rubygems.org/gems/pg_search)
-[![Build Status](https://secure.travis-ci.org/Casecommons/pg_search.svg?branch=master)](https://travis-ci.org/Casecommons/pg_search)
-[![Code Climate](https://img.shields.io/codeclimate/github/Casecommons/pg_search.svg?style=flat)](https://codeclimate.com/github/Casecommons/pg_search)
-[![Test Coverage](https://codeclimate.com/github/Casecommons/pg_search/badges/coverage.svg)](https://codeclimate.com/github/Casecommons/pg_search/coverage)
-[![Dependency Status](https://img.shields.io/gemnasium/Casecommons/pg_search.svg?style=flat)](https://gemnasium.com/Casecommons/pg_search)
-[![Inline docs](http://inch-ci.org/github/Casecommons/pg_search.svg?branch=master&style=flat)](http://inch-ci.org/github/Casecommons/pg_search)
+[![Build Status](https://github.com/Casecommons/pg_search/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Casecommons/pg_search/actions/workflows/ci.yml)
 [![Join the chat at https://gitter.im/Casecommons/pg_search](https://img.shields.io/badge/gitter-join%20chat-blue.svg)](https://gitter.im/Casecommons/pg_search?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[![Stories in Ready](https://img.shields.io/waffle/label/Casecommons/pg_search/in%20progress.svg)](https://waffle.io/Casecommons/pg_search)
 
 ## DESCRIPTION
 
 PgSearch builds named scopes that take advantage of PostgreSQL's full text
 search.
 
-Read the blog post introducing PgSearch at https://content.pivotal.io/blog/pg-search-how-i-learned-to-stop-worrying-and-love-postgresql-full-text-search
+Read the blog post introducing PgSearch at https://tanzu.vmware.com/content/blog/pg-search-how-i-learned-to-stop-worrying-and-love-postgresql-full-text-search
 
 ## REQUIREMENTS
 
-*   Ruby 2.1+
-*   ActiveRecord 4.2+
+*   Ruby 2.6+
+*   ActiveRecord 5.2+
 *   PostgreSQL 9.2+
 *   [PostgreSQL extensions](https://github.com/Casecommons/pg_search/wiki/Installing-PostgreSQL-Extensions) for certain features
 
@@ -51,10 +46,51 @@ To add PgSearch to an Active Record model, simply include the PgSearch module.
 
 ```ruby
 class Shape < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
 end
 ```    
 
+### Contents
+* [Multi-search vs. search scopes](#multi-search-vs-search-scopes)
+* [Multi-search](#multi-search)
+  * [Setup](#setup)
+  * [`multisearchable`](#multisearchable)
+  * [More Options ](#more-options)
+  * [Multi-search associations](#multi-search-associations)
+  * [Searching in the global search index](#searching-in-the-global-search-index)
+  * [Chaining method calls onto the results](#chaining-method-calls-onto-the-results)
+  * [Configuring multi-search](#configuring-multi-search)
+  * [Rebuilding search documents for a given class](#rebuilding-search-documents-for-a-given-class)
+  * [Disabling multi-search indexing temporarily](#disabling-multi-search-indexing-temporarily)
+* [`pg_search_scope`](#pg_search_scope)
+  * [Searching against one column](#searching-against-one-column)
+  * [Searching against multiple columns](#searching-against-multiple-columns)
+  * [Dynamic search scopes](#dynamic-search-scopes)
+  * [Searching through associations](#searching-through-associations)
+* [Searching using different search features](#searching-using-different-search-features)
+  * [`:tsearch` (Full Text Search)](#tsearch-full-text-search)
+    * [Weighting](#weighting)
+    * [`:prefix` (PostgreSQL 8.4 and newer only)](#prefix-postgresql-84-and-newer-only)
+    * [`:negation`](#negation)
+    * [`:dictionary`](#dictionary)
+    * [`:normalization`](#normalization)
+    * [`:any_word`](#any_word)
+    * [`:sort_only`](#sort_only)
+    * [`:highlight`](#highlight)
+  * [`:dmetaphone` (Double Metaphone soundalike search)](#dmetaphone-double-metaphone-soundalike-search)
+  * [`:trigram` (Trigram search)](#trigram-trigram-search)
+    * [`:threshold`](#threshold)
+    * [`:word_similarity`](#word_similarity)
+* [Limiting Fields When Combining Features](#limiting-fields-when-combining-features)
+* [Ignoring accent marks](#ignoring-accent-marks)
+* [Using tsvector columns](#using-tsvector-columns)
+  * [Combining multiple tsvectors](#combining-multiple-tsvectors)
+* [Configuring ranking and ordering](#configuring-ranking-and-ordering)
+  * [`:ranked_by` (Choosing a ranking algorithm)](#ranked_by-choosing-a-ranking-algorithm)
+  * [`:order_within_rank` (Breaking ties)](#order_within_rank-breaking-ties)
+  * [`PgSearch#pg_search_rank` (Reading a record's rank as a Float)](#pgsearchpg_search_rank-reading-a-records-rank-as-a-float)
+  * [Search rank and chained scopes](#search-rank-and-chained-scopes)
+
 ### Multi-search vs. search scopes
 
 pg_search supports two different techniques for searching, multi-search and
@@ -89,13 +125,13 @@ multisearchable in its class definition.
 
 ```ruby
 class EpicPoem < ActiveRecord::Base
-  include PgSearch
-  multisearchable :against => [:title, :author]
+  include PgSearch::Model
+  multisearchable against: [:title, :author]
 end
 
 class Flower < ActiveRecord::Base
-  include PgSearch
-  multisearchable :against => :color
+  include PgSearch::Model
+  multisearchable against: :color
 end
 ```
 
@@ -114,15 +150,15 @@ particular record should be included.
 
 ```ruby
 class Convertible < ActiveRecord::Base
-  include PgSearch
-  multisearchable :against => [:make, :model],
-                  :if => :available_in_red?
+  include PgSearch::Model
+  multisearchable against: [:make, :model],
+                  if: :available_in_red?
 end
 
 class Jalopy < ActiveRecord::Base
-  include PgSearch
-  multisearchable :against => [:make, :model],
-                  :if => lambda { |record| record.model_year > 1970 }
+  include PgSearch::Model
+  multisearchable against: [:make, :model],
+                  if: lambda { |record| record.model_year > 1970 }
 end
 ```
 
@@ -134,9 +170,9 @@ timestamp.
 
 ```ruby
 class AntipatternExample
-  include PgSearch
-  multisearchable :against => [:contents],
-                  :if => :published?
+  include PgSearch::Model
+  multisearchable against: [:contents],
+                  if: :published?
 
   def published?
     published_at < Time.now
@@ -144,8 +180,8 @@ class AntipatternExample
 end
 
 problematic_record = AntipatternExample.create!(
-  :contents => "Using :if with a timestamp",
-  :published_at => 10.minutes.from_now
+  contents: "Using :if with a timestamp",
+  published_at: 10.minutes.from_now
 )
 
 problematic_record.published?     # => false
@@ -162,6 +198,51 @@ problematic_record.published?     # => true
 PgSearch.multisearch("timestamp") # => Includes problematic_record
 ```
 
+#### More Options 
+
+**Conditionally update pg_search_documents**
+
+You can specify an `:update_if` parameter to conditionally update pg_search documents. For example:
+
+```ruby
+multisearchable(
+    against: [:body],
+    update_if: :body_changed?
+  )
+```
+
+**Specify additional attributes to be saved on the pg_search_documents table**
+
+You can specify `:additional_attributes` to be saved within the `pg_search_documents` table. For example, perhaps you are indexing a book model and an article model and wanted to include the author_id.
+
+First, we need to add a reference to author to the migration creating our `pg_search_documents` table.
+
+```ruby
+  create_table :pg_search_documents do |t|
+    t.text :content
+    t.references :author, index: true
+    t.belongs_to :searchable, polymorphic: true, index: true
+    t.timestamps null: false
+  end
+```
+
+Then, we can send in this additional attribute in a lambda
+
+```ruby
+  multisearchable(
+    against: [:title, :body],
+    additional_attributes: -> (article) { { author_id: article.author_id } }
+  )
+```
+
+This allows much faster searches without joins later on by doing something like:
+
+```ruby
+PgSearch.multisearch(params['search']).where(author_id: 2)
+```
+
+*NOTE: You must currently manually call `record.update_pg_search_document` for the additional attribute to be included in the pg_search_documents table*
+
 #### Multi-search associations
 
 Two associations are built automatically. On the original record, there is a
@@ -170,7 +251,7 @@ record, and on the PgSearch::Document record there is a belongs_to :searchable
 polymorphic association pointing back to the original record.
 
 ```ruby
-odyssey = EpicPoem.create!(:title => "Odyssey", :author => "Homer")
+odyssey = EpicPoem.create!(title: "Odyssey", author: "Homer")
 search_document = odyssey.pg_search_document #=> PgSearch::Document instance
 search_document.searchable #=> #<EpicPoem id: 1, title: "Odyssey", author: "Homer">
 ```
@@ -181,8 +262,8 @@ To fetch the PgSearch::Document entries for all of the records that match a
 given query, use PgSearch.multisearch.
 
 ```ruby
-odyssey = EpicPoem.create!(:title => "Odyssey", :author => "Homer")
-rose = Flower.create!(:color => "Red")
+odyssey = EpicPoem.create!(title: "Odyssey", author: "Homer")
+rose = Flower.create!(color: "Red")
 PgSearch.multisearch("Homer") #=> [#<PgSearch::Document searchable: odyssey>]
 PgSearch.multisearch("Red") #=> [#<PgSearch::Document searchable: rose>]
 ```
@@ -196,7 +277,7 @@ receive SQL requests when necessary.
 
 ```ruby
 PgSearch.multisearch("Bertha").limit(10)
-PgSearch.multisearch("Juggler").where(:searchable_type => "Occupation")
+PgSearch.multisearch("Juggler").where(searchable_type: "Occupation")
 PgSearch.multisearch("Alamo").page(3).per(30)
 PgSearch.multisearch("Diagonal").find_each do |document|
   puts document.searchable.updated_at
@@ -213,8 +294,8 @@ PgSearch.multisearch_options in an initializer:
 
 ```ruby
 PgSearch.multisearch_options = {
-  :using => [:tsearch, :trigram],
-  :ignoring => :accents
+  using: [:tsearch, :trigram],
+  ignoring: :accents
 }
 ```
 
@@ -235,7 +316,7 @@ To remove all of the documents for a given class, you can simply delete all of
 the PgSearch::Document records.
 
 ```ruby
-PgSearch::Document.delete_all(:searchable_type => "Animal")
+PgSearch::Document.delete_by(searchable_type: "Animal")
 ```
 
 To regenerate the documents for a given class, run:
@@ -251,7 +332,14 @@ is your base class. You can prevent ```rebuild``` from deleting your records
 like so:
 
 ```ruby
-PgSearch::Multisearch.rebuild(Product, false)
+PgSearch::Multisearch.rebuild(Product, clean_up: false)
+```
+
+```rebuild``` runs inside a single transaction. To run outside of a transaction,
+you can pass ```transactional: false``` like so:
+
+```ruby
+PgSearch::Multisearch.rebuild(Product, transactional: false)
 ```
 
 Rebuild is also available as a Rake task, for convenience.
@@ -271,7 +359,7 @@ the pg_search_documents table all at once. However, if you call any dynamic
 methods in :against, the following strategy will be used:
 
 ```ruby
-PgSearch::Document.delete_all(:searchable_type => "Ingredient")
+PgSearch::Document.delete_all(searchable_type: "Ingredient")
 Ingredient.find_each { |record| record.update_pg_search_document }
 ```
 
@@ -295,11 +383,11 @@ class Movie < ActiveRecord::Base
 
   # More sophisticated approach
   def self.rebuild_pg_search_documents
-    connection.execute <<-SQL
+    connection.execute <<~SQL.squish
      INSERT INTO pg_search_documents (searchable_type, searchable_id, content, created_at, updated_at)
        SELECT 'Movie' AS searchable_type,
               movies.id AS searchable_id,
-              (movies.name || ' ' || directors.name) AS content,
+              CONCAT_WS(' ', movies.name, directors.name) AS content,
               now() AS created_at,
               now() AS updated_at
        FROM movies
@@ -309,6 +397,7 @@ class Movie < ActiveRecord::Base
   end
 end
 ```
+**Note:** If using PostgreSQL before 9.1, replace the `CONCAT_WS()` function call with double-pipe concatenation, eg. `(movies.name || ' ' || directors.name)`. However, now be aware that if *any* of the joined values is NULL then the final `content` value will also be NULL, whereas `CONCAT_WS()` will selectively ignore NULL values.
 
 #### Disabling multi-search indexing temporarily
 
@@ -336,8 +425,8 @@ To search against a column, pass a symbol as the :against option.
 
 ```ruby
 class BlogPost < ActiveRecord::Base
-  include PgSearch
-  pg_search_scope :search_by_title, :against => :title
+  include PgSearch::Model
+  pg_search_scope :search_by_title, against: :title
 end
 ```
 
@@ -345,8 +434,8 @@ We now have an ActiveRecord scope named search_by_title on our BlogPost model.
 It takes one parameter, a search query string.
 
 ```ruby
-BlogPost.create!(:title => "Recent Developments in the World of Pastrami")
-BlogPost.create!(:title => "Prosciutto and You: A Retrospective")
+BlogPost.create!(title: "Recent Developments in the World of Pastrami")
+BlogPost.create!(title: "Prosciutto and You: A Retrospective")
 BlogPost.search_by_title("pastrami") # => [#<BlogPost id: 2, title: "Recent Developments in the World of Pastrami">]
 ```
 
@@ -356,16 +445,16 @@ Just pass an Array if you'd like to search more than one column.
 
 ```ruby
 class Person < ActiveRecord::Base
-  include PgSearch
-  pg_search_scope :search_by_full_name, :against => [:first_name, :last_name]
+  include PgSearch::Model
+  pg_search_scope :search_by_full_name, against: [:first_name, :last_name]
 end
 ```
 
 Now our search query can match either or both of the columns.
 
 ```ruby
-person_1 = Person.create!(:first_name => "Grant", :last_name => "Hill")
-person_2 = Person.create!(:first_name => "Hugh", :last_name => "Grant")
+person_1 = Person.create!(first_name: "Grant", last_name: "Hill")
+person_2 = Person.create!(first_name: "Hugh", last_name: "Grant")
 
 Person.search_by_full_name("Grant") # => [person_1, person_2]
 Person.search_by_full_name("Grant Hill") # => [person_1]
@@ -383,18 +472,18 @@ value if you wanted.
 
 ```ruby
 class Person < ActiveRecord::Base
-  include PgSearch
-  pg_search_scope :search_by_name, lambda do |name_part, query|
+  include PgSearch::Model
+  pg_search_scope :search_by_name, lambda { |name_part, query|
     raise ArgumentError unless [:first, :last].include?(name_part)
     {
-      :against => name_part,
-      :query => query
+      against: name_part,
+      query: query
     }
-  end
+  }
 end
 
-person_1 = Person.create!(:first_name => "Grant", :last_name => "Hill")
-person_2 = Person.create!(:first_name => "Hugh", :last_name => "Grant")
+person_1 = Person.create!(first_name: "Grant", last_name: "Hill")
+person_2 = Person.create!(first_name: "Hugh", last_name: "Grant")
 
 Person.search_by_name :first, "Grant" # => [person_1]
 Person.search_by_name :last, "Grant" # => [person_2]
@@ -421,14 +510,14 @@ class Cheese < ActiveRecord::Base
 end
 
 class Salami < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
 
   belongs_to :cracker
-  has_many :cheeses, :through => :cracker
+  has_many :cheeses, through: :cracker
 
-  pg_search_scope :tasty_search, :associated_against => {
-    :cheeses => [:kind, :brand],
-    :cracker => :kind
+  pg_search_scope :tasty_search, associated_against: {
+    cheeses: [:kind, :brand],
+    cracker: :kind
   }
 end
 
@@ -436,13 +525,13 @@ salami_1 = Salami.create!
 salami_2 = Salami.create!
 salami_3 = Salami.create!
 
-limburger = Cheese.create!(:kind => "Limburger")
-brie = Cheese.create!(:kind => "Brie")
-pepper_jack = Cheese.create!(:kind => "Pepper Jack")
+limburger = Cheese.create!(kind: "Limburger")
+brie = Cheese.create!(kind: "Brie")
+pepper_jack = Cheese.create!(kind: "Pepper Jack")
 
-Cracker.create!(:kind => "Black Pepper", :cheeses => [brie], :salami => salami_1)
-Cracker.create!(:kind => "Ritz", :cheeses => [limburger, pepper_jack], :salami => salami_2)
-Cracker.create!(:kind => "Graham", :cheeses => [limburger], :salami => salami_3)
+Cracker.create!(kind: "Black Pepper", cheeses: [brie], salami: salami_1)
+Cracker.create!(kind: "Ritz", cheeses: [limburger, pepper_jack], salami: salami_2)
+Cracker.create!(kind: "Graham", cheeses: [limburger], salami: salami_3)
 
 Salami.tasty_search("pepper") # => [salami_1, salami_2]
 ```
@@ -456,8 +545,8 @@ search techniques.
 
 ```ruby
 class Beer < ActiveRecord::Base
-  include PgSearch
-  pg_search_scope :search_name, :against => :name, :using => [:tsearch, :trigram, :dmetaphone]
+  include PgSearch::Model
+  pg_search_scope :search_name, against: :name, using: [:tsearch, :trigram, :dmetaphone]
 end
 ```
 
@@ -482,11 +571,11 @@ subtitle, and finally the content.
 
 ```ruby
 class NewsArticle < ActiveRecord::Base
-  include PgSearch
-  pg_search_scope :search_full_text, :against => {
-    :title => 'A',
-    :subtitle => 'B',
-    :content => 'C'
+  include PgSearch::Model
+  pg_search_scope :search_full_text, against: {
+    title: 'A',
+    subtitle: 'B',
+    content: 'C'
   }
 end
 ```
@@ -497,8 +586,8 @@ weight. If you omit the weight, a default will be used.
 
 ```ruby
 class NewsArticle < ActiveRecord::Base
-  include PgSearch
-  pg_search_scope :search_full_text, :against => [
+  include PgSearch::Model
+  pg_search_scope :search_full_text, against: [
     [:title, 'A'],
     [:subtitle, 'B'],
     [:content, 'C']
@@ -506,10 +595,10 @@ class NewsArticle < ActiveRecord::Base
 end
 
 class NewsArticle < ActiveRecord::Base
-  include PgSearch
-  pg_search_scope :search_full_text, :against => [
+  include PgSearch::Model
+  pg_search_scope :search_full_text, against: [
     [:title, 'A'],
-    {:subtitle => 'B'},
+    {subtitle: 'B'},
     :content
   ]
 end
@@ -524,17 +613,17 @@ shown in the following example.
 
 ```ruby
 class Superhero < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
   pg_search_scope :whose_name_starts_with,
-                  :against => :name,
-                  :using => {
-                    :tsearch => {:prefix => true}
+                  against: :name,
+                  using: {
+                    tsearch: { prefix: true }
                   }
 end
 
-batman = Superhero.create :name => 'Batman'
-batgirl = Superhero.create :name => 'Batgirl'
-robin = Superhero.create :name => 'Robin'
+batman = Superhero.create name: 'Batman'
+batgirl = Superhero.create name: 'Batgirl'
+robin = Superhero.create name: 'Robin'
 
 Superhero.whose_name_starts_with("Bat") # => [batman, batgirl]
 ```
@@ -553,18 +642,18 @@ term that you were trying to exclude.
 
 ```ruby
 class Animal < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
   pg_search_scope :with_name_matching,
-                  :against => :name,
-                  :using => {
-                    :tsearch => {:negation => true}
+                  against: :name,
+                  using: {
+                    tsearch: {negation: true}
                   }
 end
 
-one_fish = Animal.create(:name => "one fish")
-two_fish = Animal.create(:name => "two fish")
-red_fish = Animal.create(:name => "red fish")
-blue_fish = Animal.create(:name => "blue fish")
+one_fish = Animal.create(name: "one fish")
+two_fish = Animal.create(name: "two fish")
+red_fish = Animal.create(name: "red fish")
+blue_fish = Animal.create(name: "blue fish")
 
 Animal.with_name_matching("fish !red !blue") # => [one_fish, two_fish]
 ```
@@ -582,22 +671,22 @@ dictionary will be used.
 
 ```ruby
 class BoringTweet < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
   pg_search_scope :kinda_matching,
-                  :against => :text,
-                  :using => {
-                    :tsearch => {:dictionary => "english"}
+                  against: :text,
+                  using: {
+                    tsearch: {dictionary: "english"}
                   }
   pg_search_scope :literally_matching,
-                  :against => :text,
-                  :using => {
-                    :tsearch => {:dictionary => "simple"}
+                  against: :text,
+                  using: {
+                    tsearch: {dictionary: "simple"}
                   }
 end
 
-sleepy = BoringTweet.create! :text => "I snoozed my alarm for fourteen hours today. I bet I can beat that tomorrow! #sleepy"
-sleeping = BoringTweet.create! :text => "You know what I like? Sleeping. That's what. #enjoyment"
-sleeper = BoringTweet.create! :text => "Have you seen Woody Allen's movie entitled Sleeper? Me neither. #boycott"
+sleepy = BoringTweet.create! text: "I snoozed my alarm for fourteen hours today. I bet I can beat that tomorrow! #sleepy"
+sleeping = BoringTweet.create! text: "You know what I like? Sleeping. That's what. #enjoyment"
+sleeper = BoringTweet.create! text: "Have you seen Woody Allen's movie entitled Sleeper? Me neither. #boycott"
 
 BoringTweet.kinda_matching("sleeping") # => [sleepy, sleeping, sleeper]
 BoringTweet.literally_matching("sleeping") # => [sleeping]
@@ -626,18 +715,18 @@ their numbers together.
 
 ```ruby
 class BigLongDocument < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
   pg_search_scope :regular_search,
-                  :against => :text
+                  against: :text
 
   pg_search_scope :short_search,
-                  :against => :text,
-                  :using => {
-                    :tsearch => {:normalization => 2}
+                  against: :text,
+                  using: {
+                    tsearch: {normalization: 2}
                   }
 
-long = BigLongDocument.create!(:text => "Four score and twenty years ago")
-short = BigLongDocument.create!(:text => "Four score")
+long = BigLongDocument.create!(text: "Four score and twenty years ago")
+short = BigLongDocument.create!(text: "Four score")
 
 BigLongDocument.regular_search("four score") #=> [long, short]
 BigLongDocument.short_search("four score") #=> [short, long]
@@ -650,20 +739,20 @@ models containing any word in the search terms.
 
 ```ruby
 class Number < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
   pg_search_scope :search_any_word,
-                  :against => :text,
-                  :using => {
-                    :tsearch => {:any_word => true}
+                  against: :text,
+                  using: {
+                    tsearch: {any_word: true}
                   }
 
   pg_search_scope :search_all_words,
-                  :against => :text
+                  against: :text
 end
 
-one = Number.create! :text => 'one'
-two = Number.create! :text => 'two'
-three = Number.create! :text => 'three'
+one = Number.create! text: 'one'
+two = Number.create! text: 'two'
+three = Number.create! text: 'three'
 
 Number.search_any_word('one two three') # => [one, two, three]
 Number.search_all_words('one two three') # => []
@@ -676,19 +765,19 @@ but will not include it in the query's WHERE condition.
 
 ```ruby
 class Person < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
   pg_search_scope :search,
-                  :against => :name,
-                  :using => {
-                    :tsearch => {:any_word => true}
-                    :dmetaphone => {:any_word => true, :sort_only => true}
+                  against: :name,
+                  using: {
+                    tsearch: {any_word: true},
+                    dmetaphone: {any_word: true, sort_only: true}
                   }
 end
 
-exact = Person.create!(:name => 'ash hines')
-one_exact_one_close = Person.create!(:name => 'ash heinz')
-one_exact = Person.create!(:name => 'ash smith')
-one_close = Person.create!(:name => 'leigh heinz')
+exact = Person.create!(name: 'ash hines')
+one_exact_one_close = Person.create!(name: 'ash heinz')
+one_exact = Person.create!(name: 'ash smith')
+one_close = Person.create!(name: 'leigh heinz')
 
 Person.search('ash hines') # => [exact, one_exact_one_close, one_exact]
 ```
@@ -701,14 +790,14 @@ Adding .with_pg_search_highlight after the pg_search_scope you can access to
 
 ```ruby
 class Person < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
   pg_search_scope :search,
                   against: :bio,
                   using: {
                     tsearch: {
                       highlight: {
-                        StartSel: '<start>',
-                        StopSel: '<stop>',
+                        StartSel: '<b>',
+                        StopSel: '</b>',
                         MaxWords: 123,
                         MinWords: 456,
                         ShortWord: 4,
@@ -755,16 +844,16 @@ The following example shows how to use :dmetaphone.
 
 ```ruby
 class Word < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
   pg_search_scope :that_sounds_like,
-                  :against => :spelling,
-                  :using => :dmetaphone
+                  against: :spelling,
+                  using: :dmetaphone
 end
 
-four = Word.create! :spelling => 'four'
-far = Word.create! :spelling => 'far'
-fur = Word.create! :spelling => 'fur'
-five = Word.create! :spelling => 'five'
+four = Word.create! spelling: 'four'
+far = Word.create! spelling: 'far'
+fur = Word.create! spelling: 'fur'
+five = Word.create! spelling: 'five'
 
 Word.that_sounds_like("fir") # => [four, far, fur]
 ```
@@ -786,16 +875,16 @@ feature can be used.
 
 ```ruby
 class Website < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
   pg_search_scope :kinda_spelled_like,
-                  :against => :name,
-                  :using => :trigram
+                  against: :name,
+                  using: :trigram
 end
 
-yahooo = Website.create! :name => "Yahooo!"
-yohoo = Website.create! :name => "Yohoo!"
-gogle = Website.create! :name => "Gogle"
-facebook = Website.create! :name => "Facebook"
+yahooo = Website.create! name: "Yahooo!"
+yohoo = Website.create! name: "Yohoo!"
+gogle = Website.create! name: "Gogle"
+facebook = Website.create! name: "Facebook"
 
 Website.kinda_spelled_like("Yahoo!") # => [yahooo, yohoo]
 ```
@@ -811,26 +900,26 @@ threshold will force a table scan as the derived query uses the
 
 ```ruby
 class Vegetable < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
 
   pg_search_scope :strictly_spelled_like,
-                  :against => :name,
-                  :using => {
-                    :trigram => {
-                      :threshold => 0.5
+                  against: :name,
+                  using: {
+                    trigram: {
+                      threshold: 0.5
                     }
                   }
 
   pg_search_scope :roughly_spelled_like,
-                  :against => :name,
-                  :using => {
-                    :trigram => {
-                      :threshold => 0.1
+                  against: :name,
+                  using: {
+                    trigram: {
+                      threshold: 0.1
                     }
                   }
 end
 
-cauliflower = Vegetable.create! :name => "cauliflower"
+cauliflower = Vegetable.create! name: "cauliflower"
 
 Vegetable.roughly_spelled_like("couliflower") # => [cauliflower]
 Vegetable.strictly_spelled_like("couliflower") # => [cauliflower]
@@ -839,6 +928,37 @@ Vegetable.roughly_spelled_like("collyflower") # => [cauliflower]
 Vegetable.strictly_spelled_like("collyflower") # => []
 ```
 
+##### :word_similarity
+
+Allows you to match words in longer strings.
+By default, trigram searches use `%` or `similarity()` as a similarity value.
+Set `word_similarity` to `true` to opt for `<%` and `word_similarity` instead.
+This causes the trigram search to use the similarity of the query term 
+and the word with greatest similarity.
+
+```ruby
+class Sentence < ActiveRecord::Base
+  include PgSearch::Model
+
+  pg_search_scope :similarity_like,
+                  against: :name,
+                  using: {
+                    trigram: {
+                      word_similarity: true
+                    }
+                  }
+
+  pg_search_scope :word_similarity_like,
+                  against: :name,
+                  using: [:trigram]
+end
+
+sentence = Sentence.create! name: "Those are two words."
+
+Sentence.similarity_like("word") # => []
+Sentence.word_similarity_like("word") # => [sentence]
+```
+
 ### Limiting Fields When Combining Features 
 
 Sometimes when doing queries combining different features you 
@@ -849,14 +969,14 @@ which fields using the 'only' option:
 
 ```ruby
 class Image < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
 
   pg_search_scope :combined_search,
-                  :against => [:file_name, :short_description, :long_description]
-                  :using => {
-                    :tsearch => { :dictionary  => 'english' },
-                    :trigram => {
-                      :only => [:file_name, :short_description]
+                  against: [:file_name, :short_description, :long_description]
+                  using: {
+                    tsearch: { dictionary: 'english' },
+                    trigram: {
+                      only: [:file_name, :short_description]
                     }
                   }
 
@@ -884,15 +1004,15 @@ must be installed before this feature can be used.
 
 ```ruby
 class SpanishQuestion < ActiveRecord::Base
-  include PgSearch
+  include PgSearch::Model
   pg_search_scope :gringo_search,
-                  :against => :word,
-                  :ignoring => :accents
+                  against: :word,
+                  ignoring: :accents
 end
 
-what = SpanishQuestion.create(:word => "Qué")
-how_many = SpanishQuestion.create(:word => "Cuánto")
-how = SpanishQuestion.create(:word => "Cómo")
+what = SpanishQuestion.create(word: "Qué")
+how_many = SpanishQuestion.create(word: "Cuánto")
+how = SpanishQuestion.create(word: "Cómo")
 
 SpanishQuestion.gringo_search("Que") # => [what]
 SpanishQuestion.gringo_search("Cüåñtô") # => [how_many]
@@ -929,8 +1049,8 @@ To use this functionality you'll need to do a few things:
 
     ```ruby
     pg_search_scope :fast_content_search,
-                    :against => :content,
-                    :using => {
+                    against: :content,
+                    using: {
                       dmetaphone: {
                         tsvector_column: 'tsvector_content_dmetaphone'
                       },
@@ -941,13 +1061,6 @@ To use this functionality you'll need to do a few things:
                       trigram: {} # trigram does not use tsvectors
                     }
     ```
-*   You cannot dump a `tsvector` column to `schema.rb`. Instead, you need to switch to using the native PostgreSQL SQL format schema dump.
-    In your `config/application.rb` you should set
-
-        config.active_record.schema_format = :sql
-        
-    Read more about it here: http://guides.rubyonrails.org/migrations.html#types-of-schema-dumps
-
 
 Please note that the :against column is only used when the tsvector_column is
 not present for the search type.
@@ -958,26 +1071,26 @@ It's possible to search against more than one tsvector at a time. This could be
 
 ```ruby
 pg_search_scope :search_title,
-                :against => :title,
-                :using => {
-                  :tsearch => {
-                    :tsvector_column => "title_tsvector"
+                against: :title,
+                using: {
+                  tsearch: {
+                    tsvector_column: "title_tsvector"
                   }
                 }
 
 pg_search_scope :search_body,
-                :against => :body,
-                :using => {
-                  :tsearch => {
-                    :tsvector_column => "body_tsvector"
+                against: :body,
+                using: {
+                  tsearch: {
+                    tsvector_column: "body_tsvector"
                   }
                 }
 
 pg_search_scope :search_title_and_body,
-                :against => [:title, :body],
-                :using => {
-                  :tsearch => {
-                    :tsvector_column => ["title_tsvector", "body_tsvector"]
+                against: [:title, :body],
+                using: {
+                  tsearch: {
+                    tsvector_column: ["title_tsvector", "body_tsvector"]
                   }
                 }
 ```
@@ -992,9 +1105,9 @@ can pass a :ranked_by option to pg_search_scope.
 
 ```ruby
 pg_search_scope :search_by_tsearch_but_rank_by_trigram,
-                :against => :title,
-                :using => [:tsearch],
-                :ranked_by => ":trigram"
+                against: :title,
+                using: [:tsearch],
+                ranked_by: ":trigram"
 ```
 
 Note that :ranked_by using a String to represent the ranking expression. This
@@ -1004,10 +1117,10 @@ expressions.
 
 ```ruby
 # Weighted ranking to balance multiple approaches
-:ranked_by => ":dmetaphone + (0.25 * :trigram)"
+ranked_by: ":dmetaphone + (0.25 * :trigram)"
 
 # A more complex example, where books.num_pages is an integer column in the table itself
-:ranked_by => "(books.num_pages * :trigram) + (:tsearch / 2.0)"
+ranked_by: "(books.num_pages * :trigram) + (:tsearch / 2.0)"
 ```
 
 #### :order_within_rank (Breaking ties)
@@ -1039,8 +1152,8 @@ descending by updated_at, to rank the most recently updated records first.
 
 ```ruby
 pg_search_scope :search_and_break_ties_by_latest_update,
-                :against => [:title, :content],
-                :order_within_rank => "blog_posts.updated_at DESC"
+                against: [:title, :content],
+                order_within_rank: "blog_posts.updated_at DESC"
 ```
 
 #### PgSearch#pg_search_rank (Reading a record's rank as a Float)
@@ -1077,20 +1190,16 @@ shirt_brands = ShirtBrand.search_by_name("Penguin")
 
 PgSearch would not have been possible without inspiration from texticle (now renamed
 [textacular](https://github.com/textacular/textacular)). Thanks to [Aaron
-Patterson](http://tenderlovemaking.com/) for the original version!
+Patterson](http://tenderlovemaking.com/) for the original version and to Casebook PBC (https://www.casebook.net) for gifting the community with it!
 
 ## CONTRIBUTIONS AND FEEDBACK
 
-Welcomed! Feel free to join and contribute to our [public Pivotal Tracker
-project](https://www.pivotaltracker.com/projects/228645) where we manage new
-feature ideas and bugs.
+Please read our [CONTRIBUTING guide](https://github.com/Casecommons/pg_search/blob/master/CONTRIBUTING.md).
 
 We also have a [Google Group](http://groups.google.com/group/casecommons-dev)
-for discussing pg_search and other Case Commons open source projects.
-
-Please read our [CONTRIBUTING guide](https://github.com/Casecommons/pg_search/blob/master/CONTRIBUTING.md).
+for discussing pg_search and other Casebook PBC open source projects.
 
 ## LICENSE
 
-Copyright © 2010–2017 [Case Commons, Inc](http://casecommons.org).
+Copyright © 2010–2021 [Casebook PBC](http://www.casebook.net).
 Licensed under the MIT license, see [LICENSE](/LICENSE) file.