2010-09-20 22:08:53 +02:00
|
|
|
<!-- doc/src/sgml/tsearch2.sgml -->
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2011-05-08 04:29:20 +02:00
|
|
|
<sect1 id="tsearch2" xreflabel="tsearch2">
|
2007-11-14 02:09:50 +01:00
|
|
|
<title>tsearch2</title>
|
2007-12-06 05:12:10 +01:00
|
|
|
|
2007-11-14 02:09:50 +01:00
|
|
|
<indexterm zone="tsearch2">
|
|
|
|
<primary>tsearch2</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<para>
|
2011-01-26 15:22:21 +01:00
|
|
|
The <application>tsearch2</> module provides backwards-compatible
|
2007-11-14 02:09:50 +01:00
|
|
|
text search functionality for applications that used
|
2011-01-26 15:22:21 +01:00
|
|
|
<application>tsearch2</> before text searching was integrated
|
2007-11-14 02:09:50 +01:00
|
|
|
into core <productname>PostgreSQL</productname> in release 8.3.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Portability Issues</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Although the built-in text search features were based on
|
2011-01-26 15:22:21 +01:00
|
|
|
<application>tsearch2</> and are largely similar to it,
|
2007-11-14 02:09:50 +01:00
|
|
|
there are numerous small differences that will create portability
|
|
|
|
issues for existing applications:
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<itemizedlist mark="bullet">
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Some functions' names were changed, for example <function>rank</>
|
|
|
|
to <function>ts_rank</>.
|
|
|
|
The replacement <literal>tsearch2</literal> module
|
|
|
|
provides aliases having the old names.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The built-in text search data types and functions all exist within
|
|
|
|
the system schema <literal>pg_catalog</>. In an installation using
|
2011-01-26 15:22:21 +01:00
|
|
|
<application>tsearch2</>, these objects would usually have been in
|
2007-11-14 02:09:50 +01:00
|
|
|
the <literal>public</> schema, though some users chose to place them
|
|
|
|
in a separate schema of their own. Explicitly schema-qualified
|
|
|
|
references to the objects will therefore fail in either case.
|
|
|
|
The replacement <literal>tsearch2</literal> module
|
|
|
|
provides alias objects that are stored in <literal>public</>
|
|
|
|
(or another schema if necessary) so that such references will still work.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
There is no concept of a <quote>current parser</> or <quote>current
|
|
|
|
dictionary</> in the built-in text search features, only of a current
|
|
|
|
search configuration (set by the <varname>default_text_search_config</>
|
|
|
|
parameter). While the current parser and current dictionary were used
|
|
|
|
only by functions intended for debugging, this might still pose
|
|
|
|
a porting obstacle in some cases.
|
|
|
|
The replacement <literal>tsearch2</literal> module emulates these
|
|
|
|
additional state variables and provides backwards-compatible functions
|
|
|
|
for setting and retrieving them.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
There are some issues that are not addressed by the replacement
|
|
|
|
<literal>tsearch2</literal> module, and will therefore require
|
|
|
|
application code changes in any case:
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<itemizedlist mark="bullet">
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The old <function>tsearch2</> trigger function allowed items in its
|
|
|
|
argument list to be names of functions to be invoked on the text data
|
|
|
|
before it was converted to <type>tsvector</> format. This was removed
|
|
|
|
as being a security hole, since it was not possible to guarantee that
|
|
|
|
the function invoked was the one intended. The recommended approach
|
|
|
|
if the data must be massaged before being indexed is to write a custom
|
|
|
|
trigger that does the work for itself.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Text search configuration information has been moved into core
|
|
|
|
system catalogs that are noticeably different from the tables used
|
2011-01-26 15:22:21 +01:00
|
|
|
by <application>tsearch2</>. Any applications that examined
|
2007-11-14 02:09:50 +01:00
|
|
|
or modified those tables will need adjustment.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
If an application used any custom text search configurations,
|
|
|
|
those will need to be set up in the core
|
|
|
|
catalogs using the new text search configuration SQL commands.
|
|
|
|
The replacement <literal>tsearch2</literal> module offers a little
|
|
|
|
bit of support for this by making it possible to load an old set
|
2011-01-26 15:22:21 +01:00
|
|
|
of <application>tsearch2</> configuration tables into
|
2007-11-14 02:09:50 +01:00
|
|
|
<productname>PostgreSQL</productname> 8.3. (Without the module,
|
|
|
|
it is not possible to load the configuration data because values in the
|
|
|
|
<type>regprocedure</> columns cannot be resolved to functions.)
|
|
|
|
While those configuration tables won't actually <emphasis>do</>
|
|
|
|
anything, at least their contents will be available to be consulted
|
|
|
|
while setting up an equivalent custom configuration in 8.3.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The old <function>reset_tsearch()</> and <function>get_covers()</>
|
|
|
|
functions are not supported.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The replacement <literal>tsearch2</literal> module does not define
|
|
|
|
any alias operators, relying entirely on the built-in ones.
|
|
|
|
This would only pose an issue if an application used explicitly
|
|
|
|
schema-qualified operator names, which is very uncommon.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Converting a pre-8.3 Installation</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The recommended way to update a pre-8.3 installation that uses
|
2011-01-26 15:22:21 +01:00
|
|
|
<application>tsearch2</> is:
|
2007-11-14 02:09:50 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<procedure>
|
|
|
|
<step>
|
|
|
|
<para>
|
|
|
|
Make a dump from the old installation in the usual way,
|
|
|
|
but be sure not to use <literal>-c</> (<literal>--clean</>)
|
|
|
|
option of <application>pg_dump</> or <application>pg_dumpall</>.
|
|
|
|
</para>
|
|
|
|
</step>
|
|
|
|
|
|
|
|
<step>
|
|
|
|
<para>
|
|
|
|
In the new installation, create empty database(s) and install
|
|
|
|
the replacement <literal>tsearch2</literal> module into each
|
|
|
|
database that will use text search. This must be done
|
|
|
|
<emphasis>before</> loading the dump data! If your old installation
|
2011-01-26 15:22:21 +01:00
|
|
|
had the <application>tsearch2</> objects in a schema other
|
2007-11-14 02:09:50 +01:00
|
|
|
than <literal>public</>, be sure to adjust the
|
2011-02-14 07:10:44 +01:00
|
|
|
<command>CREATE EXTENSION</> command so that the replacement
|
2007-11-14 02:09:50 +01:00
|
|
|
objects are created in that same schema.
|
|
|
|
</para>
|
|
|
|
</step>
|
|
|
|
|
|
|
|
<step>
|
|
|
|
<para>
|
|
|
|
Load the dump data. There will be quite a few errors reported
|
2011-01-26 15:22:21 +01:00
|
|
|
due to failure to recreate the original <application>tsearch2</>
|
2007-11-14 02:09:50 +01:00
|
|
|
objects. These errors can be ignored, but this means you cannot
|
|
|
|
restore the dump in a single transaction (eg, you cannot use
|
2011-02-07 00:32:27 +01:00
|
|
|
<application>pg_restore</>'s <option>-1</> switch).
|
2007-11-14 02:09:50 +01:00
|
|
|
</para>
|
|
|
|
</step>
|
|
|
|
|
|
|
|
<step>
|
|
|
|
<para>
|
2011-01-26 15:22:21 +01:00
|
|
|
Examine the contents of the restored <application>tsearch2</>
|
2007-11-14 02:09:50 +01:00
|
|
|
configuration tables (<structname>pg_ts_cfg</> and so on), and
|
|
|
|
create equivalent built-in text search configurations as needed.
|
|
|
|
You may drop the old configuration tables once you've extracted
|
|
|
|
all the useful information from them.
|
|
|
|
</para>
|
|
|
|
</step>
|
|
|
|
|
|
|
|
<step>
|
|
|
|
<para>
|
|
|
|
Test your application.
|
|
|
|
</para>
|
|
|
|
</step>
|
|
|
|
</procedure>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
At a later time you may wish to rename application references
|
|
|
|
to the alias text search objects, so that you can eventually
|
|
|
|
uninstall the replacement <literal>tsearch2</literal> module.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>References</title>
|
|
|
|
<para>
|
|
|
|
Tsearch2 Development Site
|
|
|
|
<ulink url="http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/"></ulink>
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
</sect1>
|