Initial implementation of fuzzy matching

Author: lmrodriguezr

app/models/name.rb

@@ -183,6 +183,57 @@ def all_public
       where(status: public_status, redirect: nil)
     end
 
+    ##
+    # Performs a fuzzy search for names similar to +query+. The search
+    # parameters are:
+    # - method: One of +:similarity+ (default) or +:levenshtein+
+    # - threshold: Limit to find matches,
+    #   by default 0.7 (similarity) or 3 (levenshtein)
+    # - limit: Maximum number of results to return
+    # - selection: Pre-selection of names included in the search. One of:
+    #   - all_valid: (default) All validly published names
+    #   - all_public: All publicly visible names
+    #   - valid_genera: All validly published genus names
+    #   - public_genera: All publicly visible genus names
+    #   - An ActiveRecord query on the +names+ table
+    def fuzzy_match(
+          query, method: :similarity, threshold: nil, limit: 10,
+          selection: :all_valid
+        )
+      return unless ActiveRecord::Base.connection.adapter_name == 'PostgreSQL'
+
+      case selection
+      when :all_valid
+        selection = all_valid
+      when :all_public
+        selection = all_public
+      when :valid_genera
+        selection = all_valid.where(rank: :genus)
+      when :public_genera
+        selection = all_public.where(rank: :genus)
+      end
+
+      clean_query = ActiveRecord::Base.connection.quote(query)
+      case method.to_sym
+      when :similarity
+        threshold ||= 0.7
+        selection
+          .select("name, similarity(name, #{clean_query}) AS score")
+          .where('similarity(name, ?) > ?', query, threshold)
+          .order('score DESC')
+          .limit(limit)
+      when :levenshtein
+        threshold ||= 3
+        selection
+          .select("name, levenshtein(name, #{clean_query}) AS score")
+          .where('levenshtein(name, ?) <= ?', query, threshold)
+          .order('score ASC')
+          .limit(limit)
+      else
+        raise ArgumentError, "Unsupported fuzzy match method: #{method}"
+      end
+    end
+
     # ============ --- CLASS > ETYMOLOGY --- ============
 
     def etymology_particles

db/migrate/20250821140809_add_trigram_indexes_to_names_and_pseudonyms.rb

@@ -0,0 +1,32 @@
+class AddTrigramIndexesToNamesAndPseudonyms < ActiveRecord::Migration[6.1]
+  def up
+    # Only apply if using PostgreSQL
+    if ActiveRecord::Base.connection.adapter_name == 'PostgreSQL'
+      # Enable extensions
+      execute 'CREATE EXTENSION IF NOT EXISTS fuzzystrmatch;'
+      execute 'CREATE EXTENSION IF NOT EXISTS pg_trgm;'
+
+      # Add trigram index to names.name
+      execute <<-SQL
+        CREATE INDEX index_names_on_name_trgm ON names
+        USING gin (name gin_trgm_ops);
+      SQL
+      # Add trigram index to pseudonyms.pseudonym
+      execute <<-SQL
+        CREATE INDEX index_pseudonyms_on_pseudonym_trgm ON pseudonyms
+        USING gin (pseudonym gin_trgm_ops);
+      SQL
+    end
+  end
+
+  def down
+    if ActiveRecord::Base.connection.adapter_name == 'PostgreSQL'
+      execute 'DROP INDEX IF EXISTS index_names_on_name_trgm;'
+      execute 'DROP INDEX IF EXISTS index_pseudonyms_on_pseudonym_trgm;'
+      # Safer to keep them, no need to remove them
+      # execute 'DROP EXTENSION IF EXISTS fuzzystrmatch;'
+      # execute 'DROP EXTENSION IF EXISTS pg_trgm;'
+    end
+  end
+end
+

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema.define(version: 2025_08_03_153338) do
+ActiveRecord::Schema.define(version: 2025_08_21_140809) do
 
   create_table "action_text_rich_texts", force: :cascade do |t|
     t.string "name", null: false
@@ -45,7 +45,7 @@
   end
 
   create_table "active_storage_variant_records", force: :cascade do |t|
-    t.bigint "blob_id", null: false
+    t.integer "blob_id", null: false
     t.string "variation_digest", null: false
     t.index ["blob_id", "variation_digest"], name: "index_active_storage_variant_records_uniqueness", unique: true
   end

lib/tasks/fuzzy_match.rake

@@ -0,0 +1,34 @@
+namespace :name do
+  desc 'Fuzzy match a name against the Name model'
+  task :fuzzy_match, [:query] => :environment do |t, args|
+    query = args[:query]
+
+    if query.blank?
+      puts <<~HELP
+        Please provide a query string
+        Example: rake name:fuzzy_match['Escherichia coli']
+      HELP
+      exit
+    end
+
+    if ActiveRecord::Base.connection.adapter_name != 'PostgreSQL'
+      puts <<~ERROR
+        Fuzzy matching requires PostgreSQL
+        Current adapter: #{ActiveRecord::Base.connection.adapter_name}
+      ERROR
+      exit 1
+    end
+
+    puts "Searching for fuzzy matches to: '#{query}'\n\n"
+
+    matches = Name.fuzzy_match(query)
+    if matches.any?
+      matches.each do |match|
+        puts "Match: #{match.name} (Similarity: #{match.sim})"
+      end
+    else
+      puts 'No close matches found.'
+    end
+  end
+end
+