granicus.if.org Git - postgresql/blob - doc/src/sgml/fuzzystrmatch.sgml

   1 <!-- doc/src/sgml/fuzzystrmatch.sgml -->
   2
   3 <sect1 id="fuzzystrmatch" xreflabel="fuzzystrmatch">
   4  <title>fuzzystrmatch</title>
   5
   6  <indexterm zone="fuzzystrmatch">
   7   <primary>fuzzystrmatch</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <filename>fuzzystrmatch</> module provides several
  12   functions to determine similarities and distance between strings.
  13  </para>
  14
  15  <caution>
  16   <para>
  17    At present, the <function>soundex</>, <function>metaphone</>,
  18    <function>dmetaphone</>, and <function>dmetaphone_alt</> functions do
  19    not work well with multibyte encodings (such as UTF-8).
  20   </para>
  21  </caution>
  22
  23  <sect2>
  24   <title>Soundex</title>
  25
  26   <para>
  27    The Soundex system is a method of matching similar-sounding names
  28    by converting them to the same code.  It was initially used by the
  29    United States Census in 1880, 1900, and 1910.  Note that Soundex
  30    is not very useful for non-English names.
  31   </para>
  32
  33   <para>
  34    The <filename>fuzzystrmatch</> module provides two functions
  35    for working with Soundex codes:
  36   </para>
  37
  38   <indexterm>
  39    <primary>soundex</primary>
  40   </indexterm>
  41
  42   <indexterm>
  43    <primary>difference</primary>
  44   </indexterm>
  45
  46 <synopsis>
  47 soundex(text) returns text
  48 difference(text, text) returns int
  49 </synopsis>
  50
  51   <para>
  52    The <function>soundex</> function converts a string to its Soundex code.
  53    The <function>difference</> function converts two strings to their Soundex
  54    codes and then reports the number of matching code positions.  Since
  55    Soundex codes have four characters, the result ranges from zero to four,
  56    with zero being no match and four being an exact match.  (Thus, the
  57    function is misnamed &mdash; <function>similarity</> would have been
  58    a better name.)
  59   </para>
  60
  61   <para>
  62    Here are some usage examples:
  63   </para>
  64
  65 <programlisting>
  66 SELECT soundex('hello world!');
  67
  68 SELECT soundex('Anne'), soundex('Ann'), difference('Anne', 'Ann');
  69 SELECT soundex('Anne'), soundex('Andrew'), difference('Anne', 'Andrew');
  70 SELECT soundex('Anne'), soundex('Margaret'), difference('Anne', 'Margaret');
  71
  72 CREATE TABLE s (nm text);
  73
  74 INSERT INTO s VALUES ('john');
  75 INSERT INTO s VALUES ('joan');
  76 INSERT INTO s VALUES ('wobbly');
  77 INSERT INTO s VALUES ('jack');
  78
  79 SELECT * FROM s WHERE soundex(nm) = soundex('john');
  80
  81 SELECT * FROM s WHERE difference(s.nm, 'john') &gt; 2;
  82 </programlisting>
  83  </sect2>
  84
  85  <sect2>
  86   <title>Levenshtein</title>
  87
  88   <para>
  89    This function calculates the Levenshtein distance between two strings:
  90   </para>
  91
  92   <indexterm>
  93    <primary>levenshtein</primary>
  94   </indexterm>
  95
  96   <indexterm>
  97    <primary>levenshtein_less_equal</primary>
  98   </indexterm>
  99
 100 <synopsis>
 101 levenshtein(text source, text target, int ins_cost, int del_cost, int sub_cost) returns int
 102 levenshtein(text source, text target) returns int
 103 levenshtein_less_equal(text source, text target, int ins_cost, int del_cost, int sub_cost, int max_d) returns int
 104 levenshtein_less_equal(text source, text target, int max_d) returns int
 105 </synopsis>
 106
 107   <para>
 108    Both <literal>source</literal> and <literal>target</literal> can be any
 109    non-null string, with a maximum of 255 characters.  The cost parameters
 110    specify how much to charge for a character insertion, deletion, or
 111    substitution, respectively.  You can omit the cost parameters, as in
 112    the second version of the function; in that case they all default to 1.
 113   </para>
 114
 115   <para>
 116    <function>levenshtein_less_equal</function> is an accelerated version of the
 117    Levenshtein function for use when only small distances are of interest.
 118    If the actual distance is less than or equal to <literal>max_d</>,
 119    then <function>levenshtein_less_equal</function> returns the correct
 120    distance; otherwise it returns some value greater than <literal>max_d</>.
 121    If <literal>max_d</> is negative then the behavior is the same as
 122    <function>levenshtein</function>.
 123   </para>
 124
 125   <para>
 126    Examples:
 127   </para>
 128
 129 <screen>
 130 test=# SELECT levenshtein('GUMBO', 'GAMBOL');
 131  levenshtein
 132 -------------
 133            2
 134 (1 row)
 135
 136 test=# SELECT levenshtein('GUMBO', 'GAMBOL', 2,1,1);
 137  levenshtein
 138 -------------
 139            3
 140 (1 row)
 141
 142 test=# SELECT levenshtein_less_equal('extensive', 'exhaustive',2);
 143  levenshtein_less_equal
 144 ------------------------
 145                       3
 146 (1 row)
 147
 148 test=# SELECT levenshtein_less_equal('extensive', 'exhaustive',4);
 149  levenshtein_less_equal
 150 ------------------------
 151                       4
 152 (1 row)
 153 </screen>
 154  </sect2>
 155
 156  <sect2>
 157   <title>Metaphone</title>
 158
 159   <para>
 160    Metaphone, like Soundex, is based on the idea of constructing a
 161    representative code for an input string.  Two strings are then
 162    deemed similar if they have the same codes.
 163   </para>
 164
 165   <para>
 166    This function calculates the metaphone code of an input string:
 167   </para>
 168
 169   <indexterm>
 170    <primary>metaphone</primary>
 171   </indexterm>
 172
 173 <synopsis>
 174 metaphone(text source, int max_output_length) returns text
 175 </synopsis>
 176
 177   <para>
 178    <literal>source</literal> has to be a non-null string with a maximum of
 179    255 characters.  <literal>max_output_length</literal> sets the maximum
 180    length of the output metaphone code; if longer, the output is truncated
 181    to this length.
 182   </para>
 183
 184   <para>
 185    Example:
 186   </para>
 187
 188 <screen>
 189 test=# SELECT metaphone('GUMBO', 4);
 190  metaphone
 191 -----------
 192  KM
 193 (1 row)
 194 </screen>
 195  </sect2>
 196
 197  <sect2>
 198   <title>Double Metaphone</title>
 199
 200   <para>
 201    The Double Metaphone system computes two <quote>sounds like</> strings
 202    for a given input string &mdash; a <quote>primary</> and an
 203    <quote>alternate</>.  In most cases they are the same, but for non-English
 204    names especially they can be a bit different, depending on pronunciation.
 205    These functions compute the primary and alternate codes:
 206   </para>
 207
 208   <indexterm>
 209    <primary>dmetaphone</primary>
 210   </indexterm>
 211
 212   <indexterm>
 213    <primary>dmetaphone_alt</primary>
 214   </indexterm>
 215
 216 <synopsis>
 217 dmetaphone(text source) returns text
 218 dmetaphone_alt(text source) returns text
 219 </synopsis>
 220
 221   <para>
 222    There is no length limit on the input strings.
 223   </para>
 224
 225   <para>
 226    Example:
 227   </para>
 228
 229 <screen>
 230 test=# select dmetaphone('gumbo');
 231  dmetaphone
 232 ------------
 233  KMP
 234 (1 row)
 235 </screen>
 236  </sect2>
 237
 238 </sect1>