← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/dict-xsyn.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/dict-xsyn.sgml
 
1
<!-- doc/src/sgml/dict-xsyn.sgml -->
 
2
 
 
3
<sect1 id="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</> (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</> dictionary accepts the following options:
 
22
  </para>
 
23
  <itemizedlist>
 
24
   <listitem>
 
25
    <para>
 
26
     <literal>matchorig</> controls whether the original word is accepted by
 
27
     the dictionary. Default is <literal>true</>.
 
28
    </para>
 
29
   </listitem>
 
30
   <listitem>
 
31
    <para>
 
32
     <literal>matchsynonyms</> controls whether the synonyms are
 
33
     accepted by the dictionary. Default is <literal>false</>.
 
34
    </para>
 
35
   </listitem>
 
36
   <listitem>
 
37
    <para>
 
38
     <literal>keeporig</> controls whether the original word is included in
 
39
     the dictionary's output. Default is <literal>true</>.
 
40
    </para>
 
41
   </listitem>
 
42
   <listitem>
 
43
    <para>
 
44
     <literal>keepsynonyms</> controls whether the synonyms are included in
 
45
     the dictionary's output. Default is <literal>true</>.
 
46
    </para>
 
47
   </listitem>
 
48
   <listitem>
 
49
    <para>
 
50
     <literal>rules</> is the base name of the file containing the list of
 
51
     synonyms.  This file must be stored in
 
52
     <filename>$SHAREDIR/tsearch_data/</> (where <literal>$SHAREDIR</> means
 
53
     the <productname>PostgreSQL</> installation's shared-data directory).
 
54
     Its name must end in <literal>.rules</> (which is not to be included in
 
55
     the <literal>rules</> 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>#</>) 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</>, which is installed in
 
82
   <filename>$SHAREDIR/tsearch_data/</>, for an example.
 
83
  </para>
 
84
 </sect2>
 
85
 
 
86
 <sect2>
 
87
  <title>Usage</title>
 
88
 
 
89
  <para>
 
90
   Installing the <literal>dict_xsyn</> extension creates a text search
 
91
   template <literal>xsyn_template</> and a dictionary <literal>xsyn</>
 
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>