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     /opt/rt4/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     /opt/rt4/sbin/rt-setup-fulltext-index --dba postgres --dba-password secret
  30
  31 This will then tokenize and index all existing attachments in your
  32 database; it may take quite a while if your database already has a large
  33 number of tickets in it.
  34
  35 Finally, it will output an appropriate C<%FullTextSearch> configuration
  36 to add to your F<RT_SiteConfig.pm>; you will need to restart your
  37 webserver after making these changes.
  38
  39
  40 =head2 Updating the index
  41
  42 To keep the index up-to-date, you will need to run:
  43
  44     /opt/rt4/sbin/rt-fulltext-indexer
  45
  46 ...at regular intervals.  By default, this will only tokenize up to 200
  47 tickets at a time; you can adjust this upwards by passing C<--limit
  48 500>.  Larger batch sizes will take longer and consume more memory.
  49
  50 If there is already an instances of C<rt-fulltext-indexer> running, new
  51 ones will exit abnormally (with exit code 1) and the error message
  52 "rt-fulltext-indexer is already running."  You can suppress this message
  53 and end those processes normally (with exit code 0) using the C<--quiet>
  54 option; this is particularly useful when running the command via
  55 C<cron>:
  56
  57     /opt/rt4/sbin/rt-fulltext-indexer --quiet
  58
  59 =head1 MYSQL
  60
  61 On MySQL, full-text search can either be done using native support
  62 (which may use MyISAM tables on pre-5.6 versions of MySQL), or RT can
  63 integrate with the external Sphinx full-text search engine.
  64
  65 =head2 Native MySQL
  66
  67 As RT marks attachment data as C<BINARY>, MySQL cannot index this
  68 content without creating an additional table.  To create the required
  69 table (which is InnoDB on versions of MySQL which support it), run:
  70
  71     /opt/rt4/sbin/rt-setup-fulltext-index
  72
  73 If you have a non-standard database administrator username or password,
  74 you may need to pass the C<--dba> or C<--dba-password> options:
  75
  76     /opt/rt4/sbin/rt-setup-fulltext-index --dba root --dba-password secret
  77
  78 This will then tokenize and index all existing attachments in your
  79 database; it may take quite a while if your database already has a large
  80 number of tickets in it.
  81
  82 Finally, it will output an appropriate C<%FullTextSearch> configuration
  83 to add to your F<RT_SiteConfig.pm>; you will need to restart your
  84 webserver after making these changes.
  85
  86
  87 =head3 Updating the index
  88
  89 To keep the index up-to-date, you will need to run:
  90
  91     /opt/rt4/sbin/rt-fulltext-indexer
  92
  93 ...at regular intervals.  By default, this will only tokenize up to 200
  94 tickets at a time; you can adjust this upwards by passing C<--limit
  95 500>.  Larger batch sizes will take longer and consume more memory.
  96
  97 If there is already an instances of C<rt-fulltext-indexer> running, new
  98 ones will exit abnormally (with exit code 1) and the error message
  99 "rt-fulltext-indexer is already running."  You can suppress this message
 100 and end those processes normally (with exit code 0) using the C<--quiet>
 101 option; this is particularly useful when running the command via
 102 C<cron>:
 103
 104     /opt/rt4/sbin/rt-fulltext-indexer --quiet
 105
 106 =head3 Caveats
 107
 108 Searching is done in "boolean mode."  As such, the TicketSQL query
 109 C<Content LIKE 'winter 2014'> will return tickets with transactions that
 110 contain I<either> word.  To find transactions which contain both (but
 111 not necessarily adjacent), use C<Content LIKE '+winter +2014'>.  To find
 112 transactions containing the precise phrase, use C<Content LIKE '"winter
 113 2014">.
 114
 115 See the mysql documentation, at
 116 L<http://dev.mysql.com/doc/refman/5.6/en/fulltext-boolean.html>, for a
 117 list of the full capabilities.
 118
 119
 120 =head2 MySQL with Sphinx
 121
 122 RT can also integrate with the external Sphinx engine, available from
 123 L<http://sphinxsearch.com>.  Unfortunately, Sphinx integration (using
 124 SphinxSE) does require that you recompile MySQL from source.  Most
 125 distribution-provided packages for MySQL do not include SphinxSE
 126 integration, merely the external Sphinx tools; these are not sufficient
 127 for RT's needs.
 128
 129 =head3 Compiling MySQL and SphinxSE
 130
 131 MySQL 5.1 supports adding pluggable storage engines; after compiling
 132 against the appropriate version of MySQL, the F<ha_sphinx.so> file is
 133 the only that needs to be installed in production, generally into
 134 C</usr/lib/mysql/plugin/>.  It can then be enabled via:
 135
 136     INSTALL PLUGIN Sphinx SONAME "ha_sphinx.so"
 137
 138 Sphinx versions 0.9.x and 2.0.x are known-working versions, but later
 139 versions may work as well.  Complete compilation and installation
 140 instructions for MySQL with SphinxSE can be found at
 141 L<http://sphinxsearch.com/docs/current.html#sphinxse-mysql51>.
 142
 143 =head3 Creating and configuring the index
 144
 145 Once MySQL has been recompiled with SphinxSE, and Sphinx itself is
 146 installed, you may create the required SphinxSE communication table via:
 147
 148     /opt/rt4/sbin/rt-setup-fulltext-index
 149
 150 If you have a non-standard database administrator username or password,
 151 you may need to pass the C<--dba> or C<--dba-password> options:
 152
 153     /opt/rt4/sbin/rt-setup-fulltext-index --dba root --dba-password secret
 154
 155 This will also provide you with the appropriate C<%FullTextSearch>
 156 configuration to add to your F<RT_SiteConfig.pm>; you will need to
 157 restart your webserver after making these changes.  It will also print a
 158 sample Sphinx configuration, which should be placed in
 159 F</etc/sphinx.conf>, or equivalent.
 160
 161 To fill the index, you will need to run the C<indexer> command-line tool
 162 provided by Sphinx:
 163
 164     indexer rt
 165
 166 Finally, start the Sphinx search daemon:
 167
 168     searchd
 169
 170 =head3 Updating the index
 171
 172 To keep the index up-to-date, you will need to run:
 173
 174     indexer rt --rotate
 175
 176 ...at regular intervals in order to pick up new and updated attachments
 177 from RT's database.  Failure to do so will result in stale data.
 178
 179 =head3 Caveats
 180
 181 RT's integration with Sphinx relies on the use of a special index; there
 182 exist queries where the MySQL optimizer elects to I<not> use that index,
 183 instead electing to scan the table, which causes no results to be
 184 returned.  However, this is rare, and generally only occurs on complex
 185 queries.
 186
 187 Sphinx also only returns a finite number of matches to any query; this
 188 number is controlled by C<max_matches> in F</etc/sphinx.conf> and
 189 C<%FullTextSearch>'s C<MaxMatches> in C<RT_SiteConfig.pm>, which must be
 190 kept in sync.  The default, set during C<rt-setup-fulltext-index>, is
 191 10000.  This limit may lead to false negatives in search results if the
 192 maximum number of matches is reached but the results returned do not
 193 match RT's other criteria.  However, a too-large value will notably
 194 degrade performance, as it adds memory allocation overhead to every
 195 query.
 196
 197 Take, for example, the instance where Sphinx is configured to return a
 198 maximum of three results, and tickets 1, 2, 3, 4, and 5 contain the
 199 string "target", but only ticket 5 is in status "Open".  A search for
 200 C<Content LIKE 'target' AND Status = 'Open'> may return no results,
 201 despite ticket 5 matching those criteria, as Sphinx will only return
 202 tickets 1, 2, and 3 as possible matches.
 203
 204 After index creation, altering C<MaxMatches> in C<RT_SiteConfig.pm> is
 205 insufficient to adjust this limit; both C<max_matches> in
 206 F</etc/sphinx.conf> and C<%FullTextSearch>'s C<MaxMatches> in
 207 C<RT_SiteConfig.pm> must be updated.
 208
 209 =head1 ORACLE
 210
 211 =head2 Creating and configuring the index
 212
 213 Oracle supports full-text indexing natively using the Oracle Text
 214 package.  Once Oracle Text is installed and configured, run:
 215
 216     /opt/rt4/sbin/rt-setup-fulltext-index
 217
 218 If you have a non-standard database administrator username or password,
 219 you may need to pass the C<--dba> or C<--dba-password> options:
 220
 221     /opt/rt4/sbin/rt-setup-fulltext-index --dba sysdba --dba-password secret
 222
 223 This will create an Oracle CONTEXT index on the Content column in the
 224 Attachments table, as well as several preferences, functions and
 225 triggers to support this index.  The script will also output an
 226 appropriate C<%FullTextSearch> configuration to add to your
 227 F<RT_SiteConfig>.
 228
 229 =head2 Updating the index
 230
 231 To update the index, you will need to run the following at regular
 232 intervals:
 233
 234     /opt/rt4/sbin/rt-fulltext-indexer
 235
 236 This, in effect, simply runs:
 237
 238     begin
 239     ctx_ddl.sync_index('rt_fts_index', '2M');
 240     end;
 241
 242 The amount of memory used for the sync can be controlled with the
 243 C<--memory> option:
 244
 245     /opt/rt4/sbin/rt-fulltext-indexer --memory 10M
 246
 247 If there is already an instance of C<rt-fulltext-indexer> running, new
 248 ones will exit abnormally (with exit code 1) and the error message
 249 "rt-fulltext-indexer is already running."  You can suppress this message
 250 and end those processes normally (with exit code 0) using the C<--quiet>
 251 option; this is particularly useful when running the command via
 252 C<cron>:
 253
 254     /opt/rt4/sbin/rt-fulltext-indexer --quiet
 255
 256 Instead of being run via C<cron>, this may instead be run via a
 257 DBMS_JOB; read the B<Managing DML Operations for a CONTEXT Index>
 258 chapter of Oracle's B<Text Application Developer's Guide> for details
 259 how to keep the index optimized, perform garbage collection, and other
 260 tasks.
 261
 262 =head1 UNINDEXED SEARCH
 263
 264 It is also possible to enable full-text search without database indexing
 265 support, simply by setting the C<Enable> key of the C<%FullTextSearch>
 266 option to 1, while leaving C<Indexed> set to 0:
 267
 268     Set(%FullTextSearch,
 269         Enable  => 1,
 270         Indexed => 0,
 271     );
 272
 273 This is not generally suggested, as unindexed full-text searching can
 274 cause severe performance problems.
 275
 276 =head1 LIMIT ATTACHMENT SIZE
 277
 278 On some systems, very large attachments can cause memory and other
 279 performance issues for the indexer making it unable to complete
 280 indexing. See L<RT_Config.pm/"$MaxFulltextAttachmentSize"> for
 281 details on setting a maximum attachment size to index.
 282
 283 =cut