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