rt/docs/full_text_indexing.pod

   1 =head1 NAME
   2
   3 Full text indexing in RT
   4
   5 =head1 LIMITATIONS
   6
   7 While all of the below solutions can search for Unicode characters, they
   8 are not otherwise Unicode aware, and do no case folding, normalization,
   9 or the like.  That is, a string that contains C<U+0065 LATIN SMALL
  10 LETTER E> followed by C<U+0301 COMBINING ACUTE ACCENT> will not match a
  11 search for C<U+00E9 LATIN SMALL LETTER E WITH ACUTE>.  They also only
  12 know how to tokenize C<latin-1>-ish languages where words are separated
  13 by whitespace or similar characters; as such, support for searching for
  14 Japanese and Chinese content is extremely limited.
  15
  16 =head1 POSTGRES
  17
  18 =head2 Creating and configuring the index
  19
  20 Postgres 8.3 and above support full-text searching natively; to set up
  21 the required C<ts_vector> column, and create either a C<GiN> or C<GiST>
  22 index on it, run:
  23
  24     sbin/rt-setup-fulltext-index
  25
  26 If you have a non-standard database administrator username or password,
  27 you may need to pass the C<--dba> or C<--dba-password> options:
  28
  29     sbin/rt-setup-fulltext-index --dba postgres --dba-password secret
  30
  31 This will also output an appropriate C<%FullTextSearch> configuration to
  32 add to your F<RT_SiteConfig.pm>; you will need to restart your webserver
  33 after making these changes.  However, the index will also need to be
  34 filled before it can be used.  To update the index initially, run:
  35
  36     sbin/rt-fulltext-indexer --all
  37
  38 This will tokenize and index all existing attachments in your database;
  39 it may take quite a while if your database already has a large number of
  40 tickets in it.
  41
  42 =head2 Updating the index
  43
  44 To keep the index up-to-date, you will need to run:
  45
  46     sbin/rt-fulltext-indexer
  47
  48 ...at regular intervals.  By default, this will only tokenize up to 100
  49 tickets at a time; you can adjust this upwards by passing
  50 C<--limit 500>.  Larger batch sizes will take longer and
  51 consume more memory.
  52
  53 If there is already an instances of C<rt-fulltext-indexer> running, new
  54 ones will exit abnormally (with exit code 1) and the error message
  55 "rt-fulltext-indexer is already running."  You can suppress this message
  56 and end those processes normally (with exit code 0) using the C<--quiet>
  57 option; this is particularly useful when running the command via
  58 C<cron>:
  59
  60     sbin/rt-fulltext-indexer --quiet
  61
  62 =head1 MYSQL
  63
  64 MySQL does not support full-text indexing natively.  However, it does
  65 integrate with the external Sphinx engine, available from
  66 L<http://sphinxsearch.com>.  Unfortunately, Sphinx integration (using
  67 SphinxSE) does require that you recompile MySQL from source.  Most
  68 distribution-provided packages for MySQL do not include SphinxSE
  69 integration, merely the external Sphinx tools; these are not sufficient
  70 for RT's needs.
  71
  72 =head2 Compiling MySQL and SphinxSE
  73
  74 SphinxSE requires MySQL 5.0 or 5.1; later versions of MySQL have not
  75 been tested at this time.  Sphinx version 2.0.1 has been tested to work,
  76 but version 0.9.9 may work as well.  Compilation and installation
  77 instructions for MySQL with SphinxSE can be found at
  78 L<http://sphinxsearch.com/docs/current.html#sphinxse-installing>.
  79
  80 =head2 Creating and configuring the index
  81
  82 Once MySQL has been recompiled with SphinxSE, and Sphinx itself is
  83 installed, you may create the required SphinxSE communication table via:
  84
  85     sbin/rt-setup-fulltext-index
  86
  87 If you have a non-standard database administrator username or password,
  88 you may need to pass the C<--dba> or C<--dba-password> options:
  89
  90     sbin/rt-setup-fulltext-index --dba root --dba-password secret
  91
  92 This will also provide you with the appropriate C<%FullTextSearch>
  93 configuration to add to your F<RT_SiteConfig.pm>; you will need to
  94 restart your webserver after making these changes.  It will also print a
  95 sample Sphinx configuration, which should be placed in
  96 F</etc/sphinx.conf>, or equivalent.
  97
  98 To fill the index, you will need to run the C<indexer> command-line tool
  99 provided by Sphinx:
 100
 101     indexer rt
 102
 103 Finally, start the Sphinx search daemon:
 104
 105     searchd
 106
 107 =head2 Updating the index
 108
 109 To keep the index up-to-date, you will need to run:
 110
 111     indexer rt --rotate
 112
 113 ...at regular intervals in order to pick up new and updated attachments
 114 from RT's database.  Failure to do so will result in stale data.
 115
 116 =head2 Caveats
 117
 118 Sphinx only returns a finite number of matches to any query; this number
 119 is controlled by C<max_matches> in F</etc/sphinx.conf> and
 120 C<%FullTextSearch>'s C<MaxMatches> in C<RT_SiteConfig.pm>, which must be
 121 kept in sync.  The default, set during C<rt-setup-fulltext-index>, is
 122 10000.  This limit may lead to false negatives in search results if the
 123 maximum number of matches is reached but the results returned do not
 124 match RT's other criteria.
 125
 126 Take, for example, the instance where Sphinx is configured to return a
 127 maximum of three results, and tickets 1, 2, 3, 4, and 5 contain the
 128 string "target", but only ticket 5 is in status "Open".  A search for
 129 C<Content LIKE 'target' AND Status = 'Open'> may return no results,
 130 despite ticket 5 matching those criteria, as Sphinx will only return
 131 tickets 1, 2, and 3 as possible matches.
 132
 133 After index creation, altering C<MaxMatches> in C<RT_SiteConfig.pm> is
 134 insufficient to adjust this limit; both C<max_matches> in
 135 F</etc/sphinx.conf> and C<%FullTextSearch>'s C<MaxMatches> in
 136 C<RT_SiteConfig.pm> must be updated.
 137
 138 =head1 ORACLE
 139
 140 =head2 Creating and configuring the index
 141
 142 Oracle supports full-text indexing natively using the Oracle Text
 143 package.  Once Oracle Text is installed and configured, run:
 144
 145     sbin/rt-setup-fulltext-index
 146
 147 If you have a non-standard database administrator username or password,
 148 you may need to pass the C<--dba> or C<--dba-password> options:
 149
 150     sbin/rt-setup-fulltext-index --dba sysdba --dba-password secret
 151
 152 This will create an Oracle CONTEXT index on the Content column in the
 153 Attachments table, as well as several preferences, functions and
 154 triggers to support this index.  The script will also output an
 155 appropriate C<%FullTextSearch> configuration to add to your
 156 F<RT_SiteConfig>.
 157
 158 =head2 Updating the index
 159
 160 To update the index, you will need to run the following at regular
 161 intervals:
 162
 163     sbin/rt-fulltext-indexer
 164
 165 This, in effect, simply runs:
 166
 167     begin
 168     ctx_ddl.sync_index('rt_fts_index', '2M');
 169     end;
 170
 171 The amount of memory used for the sync can be controlled with the
 172 C<--memory> option:
 173
 174     rt-fulltext-indexer --memory 10M
 175
 176 If there is already an instance of C<rt-fulltext-indexer> running, new
 177 ones will exit abnormally (with exit code 1) and the error message
 178 "rt-fulltext-indexer is already running."  You can suppress this message
 179 and end those processes normally (with exit code 0) using the C<--quiet>
 180 option; this is particularly useful when running the command via
 181 C<cron>:
 182
 183     sbin/rt-fulltext-indexer --quiet
 184
 185 Instead of being run via C<cron>, this may instead be run via a
 186 DBMS_JOB; read the B<Managing DML Operations for a CONTEXT Index>
 187 chapter of Oracle's B<Text Application Developer's Guide> for details
 188 how to keep the index optimized, perform garbage collection, and other
 189 tasks.
 190
 191 =cut