1<!-- doc/src/sgml/dict-xsyn.sgml -->
2
3<sect1 id="dict-xsyn" xreflabel="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</filename> (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</literal> dictionary accepts the following options:
22  </para>
23  <itemizedlist>
24   <listitem>
25    <para>
26     <literal>matchorig</literal> controls whether the original word is accepted by
27     the dictionary. Default is <literal>true</literal>.
28    </para>
29   </listitem>
30   <listitem>
31    <para>
32     <literal>matchsynonyms</literal> controls whether the synonyms are
33     accepted by the dictionary. Default is <literal>false</literal>.
34    </para>
35   </listitem>
36   <listitem>
37    <para>
38     <literal>keeporig</literal> controls whether the original word is included in
39     the dictionary's output. Default is <literal>true</literal>.
40    </para>
41   </listitem>
42   <listitem>
43    <para>
44     <literal>keepsynonyms</literal> controls whether the synonyms are included in
45     the dictionary's output. Default is <literal>true</literal>.
46    </para>
47   </listitem>
48   <listitem>
49    <para>
50     <literal>rules</literal> is the base name of the file containing the list of
51     synonyms.  This file must be stored in
52     <filename>$SHAREDIR/tsearch_data/</filename> (where <literal>$SHAREDIR</literal> means
53     the <productname>PostgreSQL</productname> installation's shared-data directory).
54     Its name must end in <literal>.rules</literal> (which is not to be included in
55     the <literal>rules</literal> parameter).
56    </para>
57   </listitem>
58  </itemizedlist>
59  <para>
60   The rules file has the following format:
61  </para>
62  <itemizedlist>
63   <listitem>
64    <para>
65     Each line represents a group of synonyms for a single word, which is
66     given first on the line. Synonyms are separated by whitespace, thus:
67<programlisting>
68word syn1 syn2 syn3
69</programlisting>
70    </para>
71   </listitem>
72   <listitem>
73    <para>
74     The sharp (<literal>#</literal>) sign is a comment delimiter. It may appear at
75     any position in a line.  The rest of the line will be skipped.
76    </para>
77   </listitem>
78  </itemizedlist>
79
80  <para>
81   Look at <filename>xsyn_sample.rules</filename>, which is installed in
82   <filename>$SHAREDIR/tsearch_data/</filename>, for an example.
83  </para>
84 </sect2>
85
86 <sect2>
87  <title>Usage</title>
88
89  <para>
90   Installing the <literal>dict_xsyn</literal> extension creates a text search
91   template <literal>xsyn_template</literal> and a dictionary <literal>xsyn</literal>
92   based on it, with default parameters.  You can alter the
93   parameters, for example
94
95<programlisting>
96mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false);
97ALTER TEXT SEARCH DICTIONARY
98</programlisting>
99
100   or create new dictionaries based on the template.
101  </para>
102
103  <para>
104   To test the dictionary, you can try
105
106<programlisting>
107mydb=# SELECT ts_lexize('xsyn', 'word');
108      ts_lexize
109-----------------------
110 {syn1,syn2,syn3}
111
112mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true);
113ALTER TEXT SEARCH DICTIONARY
114
115mydb=# SELECT ts_lexize('xsyn', 'word');
116      ts_lexize
117-----------------------
118 {word,syn1,syn2,syn3}
119
120mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false, MATCHSYNONYMS=true);
121ALTER TEXT SEARCH DICTIONARY
122
123mydb=# SELECT ts_lexize('xsyn', 'syn1');
124      ts_lexize
125-----------------------
126 {syn1,syn2,syn3}
127
128mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true, MATCHORIG=false, KEEPSYNONYMS=false);
129ALTER TEXT SEARCH DICTIONARY
130
131mydb=# SELECT ts_lexize('xsyn', 'syn1');
132      ts_lexize
133-----------------------
134 {word}
135</programlisting>
136
137   Real-world usage will involve including it in a text search
138   configuration as described in <xref linkend="textsearch"/>.
139   That might look like this:
140
141<programlisting>
142ALTER TEXT SEARCH CONFIGURATION english
143    ALTER MAPPING FOR word, asciiword WITH xsyn, english_stem;
144</programlisting>
145
146  </para>
147 </sect2>
148
149</sect1>
150