Debian Codegraph @

doc/src/sgml/dict-xsyn.sgml

raw
1 <!-- doc/src/sgml/dict-xsyn.sgml -->
2
3 <sect1 id="dict-xsyn" xreflabel="dict_xsyn">
4 <title>dict_xsyn &mdash; example synonym full-text search dictionary</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 id="dict-xsyn-config">
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>
68 word 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 id="dict-xsyn-usage">
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>
96 mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false);
97 ALTER 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>
107 mydb=# SELECT ts_lexize('xsyn', 'word');
108 ts_lexize
109 -----------------------
110 {syn1,syn2,syn3}
111
112 mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true);
113 ALTER TEXT SEARCH DICTIONARY
114
115 mydb=# SELECT ts_lexize('xsyn', 'word');
116 ts_lexize
117 -----------------------
118 {word,syn1,syn2,syn3}
119
120 mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false, MATCHSYNONYMS=true);
121 ALTER TEXT SEARCH DICTIONARY
122
123 mydb=# SELECT ts_lexize('xsyn', 'syn1');
124 ts_lexize
125 -----------------------
126 {syn1,syn2,syn3}
127
128 mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true, MATCHORIG=false, KEEPSYNONYMS=false);
129 ALTER TEXT SEARCH DICTIONARY
130
131 mydb=# 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>
142 ALTER TEXT SEARCH CONFIGURATION english
143 ALTER MAPPING FOR word, asciiword WITH xsyn, english_stem;
144 </programlisting>
145
146 </para>
147 </sect2>
148
149 </sect1>