doc/src/sgml/dict-xsyn.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3 <sect1 id="dict-xsyn">
   4  <title>dict_xsyn</title>
   5
   6  <indexterm zone="dict-xsyn">
   7   <primary>dict_xsyn</primary>
   8  </indexterm>
   9
  10  <para>
  11   <filename>dict_xsyn</> (Extended Synonym Dictionary) is an example of an
  12   add-on dictionary template for full-text search.  This dictionary type
  13   replaces words with groups of their synonyms, and so makes it possible to
  14   search for a word using any of its synonyms.
  15  </para>
  16
  17  <sect2>
  18   <title>Configuration</title>
  19
  20   <para>
  21    A <literal>dict_xsyn</> dictionary accepts the following options:
  22   </para>
  23   <itemizedlist>
  24    <listitem>
  25     <para>
  26      <literal>keeporig</> controls whether the original word is included (if
  27      <literal>true</>), or only its synonyms (if <literal>false</>). Default
  28      is <literal>true</>.
  29     </para>
  30    </listitem>
  31    <listitem>
  32     <para>
  33      <literal>rules</> is the base name of the file containing the list of
  34      synonyms.  This file must be stored in
  35      <filename>$SHAREDIR/tsearch_data/</> (where <literal>$SHAREDIR</> means
  36      the <productname>PostgreSQL</> installation's shared-data directory).
  37      Its name must end in <literal>.rules</> (which is not to be included in
  38      the <literal>rules</> parameter).
  39     </para>
  40    </listitem>
  41   </itemizedlist>
  42   <para>
  43    The rules file has the following format:
  44   </para>
  45   <itemizedlist>
  46    <listitem>
  47     <para>
  48      Each line represents a group of synonyms for a single word, which is
  49      given first on the line. Synonyms are separated by whitespace, thus:
  50     <programlisting>
  51 word syn1 syn2 syn3
  52     </programlisting>
  53     </para>
  54    </listitem>
  55    <listitem>
  56     <para>
  57      The sharp (<literal>#</>) sign is a comment delimiter. It may appear at
  58      any position in a line.  The rest of the line will be skipped.
  59     </para>
  60    </listitem>
  61   </itemizedlist>
  62
  63   <para>
  64    Look at <filename>xsyn_sample.rules</>, which is installed in
  65    <filename>$SHAREDIR/tsearch_data/</>, for an example.
  66   </para>
  67  </sect2>
  68
  69  <sect2>
  70   <title>Usage</title>
  71
  72   <para>
  73    Running the installation script creates a text search template
  74    <literal>xsyn_template</> and a dictionary <literal>xsyn</>
  75    based on it, with default parameters.  You can alter the
  76    parameters, for example
  77
  78 <programlisting>
  79 mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false);
  80 ALTER TEXT SEARCH DICTIONARY
  81 </programlisting>
  82
  83    or create new dictionaries based on the template.
  84   </para>
  85
  86   <para>
  87    To test the dictionary, you can try
  88
  89 <programlisting>
  90 mydb=# SELECT ts_lexize('xsyn', 'word');
  91       ts_lexize
  92 -----------------------
  93  {word,syn1,syn2,syn3}
  94 </programlisting>
  95
  96    but real-world usage will involve including it in a text search
  97    configuration as described in <xref linkend="textsearch">.
  98    That might look like this:
  99
 100 <programlisting>
 101 ALTER TEXT SEARCH CONFIGURATION english
 102     ALTER MAPPING FOR word, asciiword WITH xsyn, english_stem;
 103 </programlisting>
 104
 105   </para>
 106  </sect2>
 107
 108 </sect1>