doc/src/sgml/dict-int.sgml

   1 <!-- doc/src/sgml/dict-int.sgml -->
   2
   3 <sect1 id="dict-int" xreflabel="dict_int">
   4  <title>dict_int &mdash;
   5    example full-text search dictionary for integers</title>
   6
   7  <indexterm zone="dict-int">
   8   <primary>dict_int</primary>
   9  </indexterm>
  10
  11  <para>
  12   <filename>dict_int</filename> is an example of an add-on dictionary template
  13   for full-text search.  The motivation for this example dictionary is to
  14   control the indexing of integers (signed and unsigned), allowing such
  15   numbers to be indexed while preventing excessive growth in the number of
  16   unique words, which greatly affects the performance of searching.
  17  </para>
  18
  19  <para>
  20   This module is considered <quote>trusted</quote>, that is, it can be
  21   installed by non-superusers who have <literal>CREATE</literal> privilege
  22   on the current database.
  23  </para>
  24
  25  <sect2 id="dict-int-config">
  26   <title>Configuration</title>
  27
  28   <para>
  29    The dictionary accepts three options:
  30   </para>
  31
  32   <itemizedlist>
  33    <listitem>
  34     <para>
  35      The <literal>maxlen</literal> parameter specifies the maximum number of
  36      digits allowed in an integer word.  The default value is 6.
  37     </para>
  38    </listitem>
  39    <listitem>
  40     <para>
  41      The <literal>rejectlong</literal> parameter specifies whether an overlength
  42      integer should be truncated or ignored.  If <literal>rejectlong</literal> is
  43      <literal>false</literal> (the default), the dictionary returns the first
  44      <literal>maxlen</literal> digits of the integer. If <literal>rejectlong</literal> is
  45      <literal>true</literal>, the dictionary treats an overlength integer as a stop
  46      word, so that it will not be indexed.  Note that this also means that
  47      such an integer cannot be searched for.
  48     </para>
  49    </listitem>
  50    <listitem>
  51     <para>
  52      The <literal>absval</literal> parameter specifies whether leading
  53      <quote><literal>+</literal></quote> or <quote><literal>-</literal></quote>
  54      signs should be removed from integer words.  The default
  55      is <literal>false</literal>.  When <literal>true</literal>, the sign is
  56      removed before <literal>maxlen</literal> is applied.
  57     </para>
  58    </listitem>
  59   </itemizedlist>
  60  </sect2>
  61
  62  <sect2 id="dict-int-usage">
  63   <title>Usage</title>
  64
  65   <para>
  66    Installing the <literal>dict_int</literal> extension creates a text search
  67    template <literal>intdict_template</literal> and a dictionary <literal>intdict</literal>
  68    based on it, with the default parameters.  You can alter the
  69    parameters, for example
  70
  71 <programlisting>
  72 mydb# ALTER TEXT SEARCH DICTIONARY intdict (MAXLEN = 4, REJECTLONG = true);
  73 ALTER TEXT SEARCH DICTIONARY
  74 </programlisting>
  75
  76    or create new dictionaries based on the template.
  77   </para>
  78
  79   <para>
  80    To test the dictionary, you can try
  81
  82 <programlisting>
  83 mydb# select ts_lexize('intdict', '12345678');
  84  ts_lexize
  85 -----------
  86  {123456}
  87 </programlisting>
  88
  89    but real-world usage will involve including it in a text search
  90    configuration as described in <xref linkend="textsearch"/>.
  91    That might look like this:
  92
  93 <programlisting>
  94 ALTER TEXT SEARCH CONFIGURATION english
  95     ALTER MAPPING FOR int, uint WITH intdict;
  96 </programlisting>
  97
  98   </para>
  99  </sect2>
 100
 101 </sect1>