2010-09-20 22:08:53 +02:00
|
|
|
<!-- doc/src/sgml/fuzzystrmatch.sgml -->
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2011-05-08 04:29:20 +02:00
|
|
|
<sect1 id="fuzzystrmatch" xreflabel="fuzzystrmatch">
|
2023-01-20 20:01:59 +01:00
|
|
|
<title>fuzzystrmatch — determine string similarities and distance</title>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
|
|
|
<indexterm zone="fuzzystrmatch">
|
|
|
|
<primary>fuzzystrmatch</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The <filename>fuzzystrmatch</filename> module provides several
|
2007-11-11 00:30:46 +01:00
|
|
|
functions to determine similarities and distance between strings.
|
|
|
|
</para>
|
|
|
|
|
2009-04-06 17:43:00 +02:00
|
|
|
<caution>
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
At present, the <function>soundex</function>, <function>metaphone</function>,
|
|
|
|
<function>dmetaphone</function>, and <function>dmetaphone_alt</function> functions do
|
2010-08-17 06:37:21 +02:00
|
|
|
not work well with multibyte encodings (such as UTF-8).
|
2023-04-07 23:31:51 +02:00
|
|
|
Use <function>daitch_mokotoff</function>
|
|
|
|
or <function>levenshtein</function> with such data.
|
2009-04-06 17:43:00 +02:00
|
|
|
</para>
|
|
|
|
</caution>
|
|
|
|
|
2020-02-13 21:02:35 +01:00
|
|
|
<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>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="fuzzystrmatch-soundex">
|
2007-11-11 00:30:46 +01:00
|
|
|
<title>Soundex</title>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
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.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The <filename>fuzzystrmatch</filename> module provides two functions
|
2007-12-06 05:12:10 +01:00
|
|
|
for working with Soundex codes:
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2013-07-04 17:33:08 +02:00
|
|
|
<indexterm>
|
|
|
|
<primary>soundex</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>difference</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<synopsis>
|
|
|
|
soundex(text) returns text
|
|
|
|
difference(text, text) returns int
|
|
|
|
</synopsis>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The <function>soundex</function> function converts a string to its Soundex code.
|
|
|
|
The <function>difference</function> function converts two strings to their Soundex
|
2007-12-06 05:12:10 +01:00
|
|
|
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
|
2017-10-09 03:44:17 +02:00
|
|
|
function is misnamed — <function>similarity</function> would have been
|
2007-12-06 05:12:10 +01:00
|
|
|
a better name.)
|
|
|
|
</para>
|
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
Here are some usage examples:
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<programlisting>
|
2007-11-11 00:30:46 +01:00
|
|
|
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');
|
|
|
|
|
2007-12-06 05:12:10 +01:00
|
|
|
SELECT * FROM s WHERE difference(s.nm, 'john') > 2;
|
2010-07-29 21:34:41 +02:00
|
|
|
</programlisting>
|
2007-12-06 05:12:10 +01:00
|
|
|
</sect2>
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2023-04-07 23:31:51 +02:00
|
|
|
<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 codes for its input:
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<synopsis>
|
|
|
|
daitch_mokotoff(<parameter>source</parameter> text) returns text[]
|
|
|
|
</synopsis>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The result may contain one or more codes depending on how many plausible
|
|
|
|
pronunciations there are, so it is represented as an array.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Since a Daitch-Mokotoff soundex code consists of only 6 digits,
|
|
|
|
<parameter>source</parameter> should be preferably a single word or name.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Here are some examples:
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
SELECT daitch_mokotoff('George');
|
|
|
|
daitch_mokotoff
|
|
|
|
-----------------
|
|
|
|
{595000}
|
|
|
|
|
|
|
|
SELECT daitch_mokotoff('John');
|
|
|
|
daitch_mokotoff
|
|
|
|
-----------------
|
|
|
|
{160000,460000}
|
|
|
|
|
|
|
|
SELECT daitch_mokotoff('Bierschbach');
|
|
|
|
daitch_mokotoff
|
|
|
|
-----------------------------------------------------------
|
|
|
|
{794575,794574,794750,794740,745750,745740,747500,747400}
|
|
|
|
|
|
|
|
SELECT daitch_mokotoff('Schwartzenegger');
|
|
|
|
daitch_mokotoff
|
|
|
|
-----------------
|
|
|
|
{479465}
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For matching of single names, returned text arrays can be matched
|
|
|
|
directly using the <literal>&&</literal> operator: any overlap
|
|
|
|
can be considered a match. A GIN index may
|
|
|
|
be used for efficiency, see <xref linkend="gin"/> and this example:
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
CREATE TABLE s (nm text);
|
|
|
|
CREATE INDEX ix_s_dm ON s USING gin (daitch_mokotoff(nm)) WITH (fastupdate = off);
|
|
|
|
|
|
|
|
INSERT INTO s (nm) VALUES
|
|
|
|
('Schwartzenegger'),
|
|
|
|
('John'),
|
|
|
|
('James'),
|
|
|
|
('Steinman'),
|
|
|
|
('Steinmetz');
|
|
|
|
|
|
|
|
SELECT * FROM s WHERE daitch_mokotoff(nm) && daitch_mokotoff('Swartzenegger');
|
|
|
|
SELECT * FROM s WHERE daitch_mokotoff(nm) && daitch_mokotoff('Jane');
|
|
|
|
SELECT * FROM s WHERE daitch_mokotoff(nm) && daitch_mokotoff('Jens');
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For indexing and matching of any number of names in any order, Full Text
|
|
|
|
Search features can be used. See <xref linkend="textsearch"/> and this
|
|
|
|
example:
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
CREATE FUNCTION soundex_tsvector(v_name text) RETURNS tsvector
|
|
|
|
BEGIN ATOMIC
|
|
|
|
SELECT to_tsvector('simple',
|
|
|
|
string_agg(array_to_string(daitch_mokotoff(n), ' '), ' '))
|
|
|
|
FROM regexp_split_to_table(v_name, '\s+') AS n;
|
|
|
|
END;
|
|
|
|
|
|
|
|
CREATE FUNCTION soundex_tsquery(v_name text) RETURNS tsquery
|
|
|
|
BEGIN ATOMIC
|
|
|
|
SELECT string_agg('(' || array_to_string(daitch_mokotoff(n), '|') || ')', '&')::tsquery
|
|
|
|
FROM regexp_split_to_table(v_name, '\s+') AS n;
|
|
|
|
END;
|
|
|
|
|
|
|
|
CREATE TABLE s (nm text);
|
|
|
|
CREATE INDEX ix_s_txt ON s USING gin (soundex_tsvector(nm)) WITH (fastupdate = off);
|
|
|
|
|
|
|
|
INSERT INTO s (nm) VALUES
|
|
|
|
('John Doe'),
|
|
|
|
('Jane Roe'),
|
|
|
|
('Public John Q.'),
|
|
|
|
('George Best'),
|
|
|
|
('John Yamson');
|
|
|
|
|
|
|
|
SELECT * FROM s WHERE soundex_tsvector(nm) @@ soundex_tsquery('john');
|
|
|
|
SELECT * FROM s WHERE soundex_tsvector(nm) @@ soundex_tsquery('jane doe');
|
|
|
|
SELECT * FROM s WHERE soundex_tsvector(nm) @@ soundex_tsquery('john public');
|
|
|
|
SELECT * FROM s WHERE soundex_tsvector(nm) @@ soundex_tsquery('besst, giorgio');
|
|
|
|
SELECT * FROM s WHERE soundex_tsvector(nm) @@ soundex_tsquery('Jameson John');
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
If it is desired to avoid recalculation of soundex codes during index
|
|
|
|
rechecks, an index on a separate column can be used instead of an index on
|
|
|
|
an expression. A stored generated column can be used for this; see
|
|
|
|
<xref linkend="ddl-generated-columns"/>.
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="fuzzystrmatch-levenshtein">
|
2007-12-06 05:12:10 +01:00
|
|
|
<title>Levenshtein</title>
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2007-12-06 05:12:10 +01:00
|
|
|
<para>
|
|
|
|
This function calculates the Levenshtein distance between two strings:
|
|
|
|
</para>
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2013-07-04 17:33:08 +02:00
|
|
|
<indexterm>
|
|
|
|
<primary>levenshtein</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>levenshtein_less_equal</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<synopsis>
|
2023-04-07 23:31:51 +02:00
|
|
|
levenshtein(source text, target text, ins_cost int, del_cost int, sub_cost int) returns int
|
|
|
|
levenshtein(source text, target text) returns int
|
|
|
|
levenshtein_less_equal(source text, target text, ins_cost int, del_cost int, sub_cost int, max_d int) returns int
|
|
|
|
levenshtein_less_equal(source text, target text, max_d int) returns int
|
2010-07-29 21:34:41 +02:00
|
|
|
</synopsis>
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2007-12-06 05:12:10 +01:00
|
|
|
<para>
|
|
|
|
Both <literal>source</literal> and <literal>target</literal> can be any
|
2016-01-22 18:29:07 +01:00
|
|
|
non-null string, with a maximum of 255 characters. The cost parameters
|
2008-04-03 23:13:07 +02:00
|
|
|
specify how much to charge for a character insertion, deletion, or
|
|
|
|
substitution, respectively. You can omit the cost parameters, as in
|
|
|
|
the second version of the function; in that case they all default to 1.
|
2016-01-22 18:29:07 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<function>levenshtein_less_equal</function> is an accelerated version of the
|
|
|
|
Levenshtein function for use when only small distances are of interest.
|
2017-10-09 03:44:17 +02:00
|
|
|
If the actual distance is less than or equal to <literal>max_d</literal>,
|
2016-01-22 18:29:07 +01:00
|
|
|
then <function>levenshtein_less_equal</function> returns the correct
|
2017-10-09 03:44:17 +02:00
|
|
|
distance; otherwise it returns some value greater than <literal>max_d</literal>.
|
|
|
|
If <literal>max_d</literal> is negative then the behavior is the same as
|
2016-01-22 18:29:07 +01:00
|
|
|
<function>levenshtein</function>.
|
2007-12-06 05:12:10 +01:00
|
|
|
</para>
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2007-12-06 05:12:10 +01:00
|
|
|
<para>
|
2008-04-03 23:13:07 +02:00
|
|
|
Examples:
|
2007-12-06 05:12:10 +01:00
|
|
|
</para>
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<screen>
|
2007-12-06 05:12:10 +01:00
|
|
|
test=# SELECT levenshtein('GUMBO', 'GAMBOL');
|
|
|
|
levenshtein
|
|
|
|
-------------
|
|
|
|
2
|
|
|
|
(1 row)
|
2008-04-03 23:13:07 +02:00
|
|
|
|
2017-08-12 03:04:04 +02:00
|
|
|
test=# SELECT levenshtein('GUMBO', 'GAMBOL', 2, 1, 1);
|
2008-04-03 23:13:07 +02:00
|
|
|
levenshtein
|
|
|
|
-------------
|
|
|
|
3
|
|
|
|
(1 row)
|
2010-10-19 15:51:06 +02:00
|
|
|
|
2017-08-12 03:04:04 +02:00
|
|
|
test=# SELECT levenshtein_less_equal('extensive', 'exhaustive', 2);
|
2010-10-19 15:51:06 +02:00
|
|
|
levenshtein_less_equal
|
|
|
|
------------------------
|
|
|
|
3
|
|
|
|
(1 row)
|
|
|
|
|
2017-08-12 03:04:04 +02:00
|
|
|
test=# SELECT levenshtein_less_equal('extensive', 'exhaustive', 4);
|
2010-10-19 15:51:06 +02:00
|
|
|
levenshtein_less_equal
|
|
|
|
------------------------
|
|
|
|
4
|
|
|
|
(1 row)
|
2010-07-29 21:34:41 +02:00
|
|
|
</screen>
|
2007-11-11 00:30:46 +01:00
|
|
|
</sect2>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="fuzzystrmatch-metaphone">
|
2007-12-06 05:12:10 +01:00
|
|
|
<title>Metaphone</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Metaphone, like Soundex, is based on the idea of constructing a
|
|
|
|
representative code for an input string. Two strings are then
|
|
|
|
deemed similar if they have the same codes.
|
|
|
|
</para>
|
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
This function calculates the metaphone code of an input string:
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2013-07-04 17:33:08 +02:00
|
|
|
<indexterm>
|
|
|
|
<primary>metaphone</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<synopsis>
|
2023-04-07 23:31:51 +02:00
|
|
|
metaphone(source text, max_output_length int) returns text
|
2010-07-29 21:34:41 +02:00
|
|
|
</synopsis>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
<literal>source</literal> has to be a non-null string with a maximum of
|
|
|
|
255 characters. <literal>max_output_length</literal> sets the maximum
|
|
|
|
length of the output metaphone code; if longer, the output is truncated
|
|
|
|
to this length.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
|
|
|
Example:
|
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<screen>
|
2007-12-06 05:12:10 +01:00
|
|
|
test=# SELECT metaphone('GUMBO', 4);
|
|
|
|
metaphone
|
|
|
|
-----------
|
|
|
|
KM
|
|
|
|
(1 row)
|
2010-07-29 21:34:41 +02:00
|
|
|
</screen>
|
2007-11-11 00:30:46 +01:00
|
|
|
</sect2>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="fuzzystrmatch-double-metaphone">
|
2007-12-06 05:12:10 +01:00
|
|
|
<title>Double Metaphone</title>
|
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The Double Metaphone system computes two <quote>sounds like</quote> strings
|
|
|
|
for a given input string — a <quote>primary</quote> and an
|
|
|
|
<quote>alternate</quote>. In most cases they are the same, but for non-English
|
2007-12-06 05:12:10 +01:00
|
|
|
names especially they can be a bit different, depending on pronunciation.
|
|
|
|
These functions compute the primary and alternate codes:
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2013-07-04 17:33:08 +02:00
|
|
|
<indexterm>
|
|
|
|
<primary>dmetaphone</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>dmetaphone_alt</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<synopsis>
|
2023-04-07 23:31:51 +02:00
|
|
|
dmetaphone(source text) returns text
|
|
|
|
dmetaphone_alt(source text) returns text
|
2010-07-29 21:34:41 +02:00
|
|
|
</synopsis>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2007-12-06 05:12:10 +01:00
|
|
|
There is no length limit on the input strings.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Example:
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<screen>
|
2017-08-12 03:04:04 +02:00
|
|
|
test=# SELECT dmetaphone('gumbo');
|
2007-12-06 05:12:10 +01:00
|
|
|
dmetaphone
|
|
|
|
------------
|
|
|
|
KMP
|
|
|
|
(1 row)
|
2010-07-29 21:34:41 +02:00
|
|
|
</screen>
|
2007-11-11 00:30:46 +01:00
|
|
|
</sect2>
|
|
|
|
|
|
|
|
</sect1>
|