<!-- doc/src/sgml/fuzzystrmatch.sgml -->

<sect1 id="fuzzystrmatch" xreflabel="fuzzystrmatch">
 <title>fuzzystrmatch &mdash; determine string similarities and distance</title>

 <indexterm zone="fuzzystrmatch">
  <primary>fuzzystrmatch</primary>
 </indexterm>

 <para>
  The <filename>fuzzystrmatch</filename> module provides several
  functions to determine similarities and distance between strings.
 </para>

 <caution>
  <para>
   At present, the <function>soundex</function>, <function>metaphone</function>,
   <function>dmetaphone</function>, and <function>dmetaphone_alt</function> functions do
   not work well with multibyte encodings (such as UTF-8).
   Use <function>daitch_mokotoff</function>
   or <function>levenshtein</function> with such data.
  </para>
 </caution>

 <para>
  This module is considered <quote>trusted</quote>, that is, it can be
  installed by non-superusers who have <literal>CREATE</literal> privilege
  on the current database.
 </para>

 <sect2 id="fuzzystrmatch-soundex">
  <title>Soundex</title>

  <para>
   The Soundex system is a method of matching similar-sounding names
   by converting them to the same code.  It was initially used by the
   United States Census in 1880, 1900, and 1910.  Note that Soundex
   is not very useful for non-English names.
  </para>

  <para>
   The <filename>fuzzystrmatch</filename> module provides two functions
   for working with Soundex codes:
  </para>

  <indexterm>
   <primary>soundex</primary>
  </indexterm>

  <indexterm>
   <primary>difference</primary>
  </indexterm>

<synopsis>
soundex(text) returns text
difference(text, text) returns int
</synopsis>

  <para>
   The <function>soundex</function> function converts a string to its Soundex code.
   The <function>difference</function> function converts two strings to their Soundex
   codes and then reports the number of matching code positions.  Since
   Soundex codes have four characters, the result ranges from zero to four,
   with zero being no match and four being an exact match.  (Thus, the
   function is misnamed &mdash; <function>similarity</function> would have been
   a better name.)
  </para>

  <para>
   Here are some usage examples:
  </para>

<programlisting>
SELECT soundex('hello world!');

SELECT soundex('Anne'), soundex('Ann'), difference('Anne', 'Ann');
SELECT soundex('Anne'), soundex('Andrew'), difference('Anne', 'Andrew');
SELECT soundex('Anne'), soundex('Margaret'), difference('Anne', 'Margaret');

CREATE TABLE s (nm text);

INSERT INTO s VALUES ('john');
INSERT INTO s VALUES ('joan');
INSERT INTO s VALUES ('wobbly');
INSERT INTO s VALUES ('jack');

SELECT * FROM s WHERE soundex(nm) = soundex('john');

SELECT * FROM s WHERE difference(s.nm, 'john') &gt; 2;
</programlisting>
 </sect2>

 <sect2 id="fuzzystrmatch-daitch-mokotoff">
  <title>Daitch-Mokotoff Soundex</title>

  <para>
   Like the original Soundex system, Daitch-Mokotoff Soundex matches
   similar-sounding names by converting them to the same code.
   However, Daitch-Mokotoff Soundex is significantly more useful for
   non-English names than the original system.
   Major improvements over the original system include:

   <itemizedlist spacing="compact" mark="bullet">
    <listitem>
     <para>
      The code is based on the first six meaningful letters rather than four.
     </para>
    </listitem>
    <listitem>
     <para>
      A letter or combination of letters maps into ten possible codes rather
      than seven.
     </para>
    </listitem>
    <listitem>
     <para>
      Where two consecutive letters have a single sound, they are coded as a
      single number.
     </para>
    </listitem>
    <listitem>
     <para>
      When a letter or combination of letters may have different sounds,
      multiple codes are emitted to cover all possibilities.
     </para>
    </listitem>
   </itemizedlist>
  </para>

  <indexterm>
   <primary>daitch_mokotoff</primary>
  </indexterm>

  <para>
   This function generates the Daitch-Mokotoff soundex