doc/src/sgml/test-parser.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3 <sect1 id="test-parser">
   4  <title>test_parser</title>
   5
   6  <indexterm zone="test-parser">
   7   <primary>test_parser</primary>
   8  </indexterm>
   9
  10  <para>
  11   <filename>test_parser</> is an example of a custom parser for full-text
  12   search.  It doesn't do anything especially useful, but can serve as
  13   a starting point for developing your own parser.
  14  </para>
  15
  16  <para>
  17   <filename>test_parser</> recognizes words separated by white space,
  18   and returns just two token types:
  19
  20 <programlisting>
  21 mydb=# SELECT * FROM ts_token_type('testparser');
  22  tokid | alias |  description
  23 -------+-------+---------------
  24      3 | word  | Word
  25     12 | blank | Space symbols
  26 (2 rows)
  27 </programlisting>
  28
  29   These token numbers have been chosen to be compatible with the default
  30   parser's numbering.  This allows us to use its <function>headline()</>
  31   function, thus keeping the example simple.
  32  </para>
  33
  34  <sect2>
  35   <title>Usage</title>
  36
  37   <para>
  38    Running the installation script creates a text search parser
  39    <literal>testparser</>.  It has no user-configurable parameters.
  40   </para>
  41
  42   <para>
  43    You can test the parser with, for example,
  44
  45 <programlisting>
  46 mydb=# SELECT * FROM ts_parse('testparser', 'That''s my first own parser');
  47  tokid | token
  48 -------+--------
  49      3 | That's
  50     12 |
  51      3 | my
  52     12 |
  53      3 | first
  54     12 |
  55      3 | own
  56     12 |
  57      3 | parser
  58 </programlisting>
  59   </para>
  60
  61   <para>
  62    Real-world use requires setting up a text search configuration
  63    that uses the parser.  For example,
  64
  65 <programlisting>
  66 mydb=# CREATE TEXT SEARCH CONFIGURATION testcfg ( PARSER = testparser );
  67 CREATE TEXT SEARCH CONFIGURATION
  68
  69 mydb=# ALTER TEXT SEARCH CONFIGURATION testcfg
  70 mydb-#   ADD MAPPING FOR word WITH english_stem;
  71 ALTER TEXT SEARCH CONFIGURATION
  72
  73 mydb=#  SELECT to_tsvector('testcfg', 'That''s my first own parser');
  74           to_tsvector
  75 -------------------------------
  76  'that':1 'first':3 'parser':5
  77 (1 row)
  78
  79 mydb=# SELECT ts_headline('testcfg', 'Supernovae stars are the brightest phenomena in galaxies',
  80 mydb(#                    to_tsquery('testcfg', 'star'));
  81                            ts_headline
  82 -----------------------------------------------------------------
  83  Supernovae &lt;b&gt;stars&lt;/b&gt; are the brightest phenomena in galaxies
  84 (1 row)
  85 </programlisting>
  86   </para>
  87
  88  </sect2>
  89
  90 </sect1>