dict\_xsyn {#dict-xsyn}
==========

dict\_xsyn

`dict_xsyn` (Extended Synonym Dictionary) is an example of an add-on
dictionary template for full-text search. This dictionary type replaces
words with groups of their synonyms, and so makes it possible to search
for a word using any of its synonyms.

Configuration
-------------

A `dict_xsyn` dictionary accepts the following options:

-   `matchorig` controls whether the original word is accepted by the
    dictionary. Default is `true`.

-   `matchsynonyms` controls whether the synonyms are accepted by the
    dictionary. Default is `false`.

-   `keeporig` controls whether the original word is included in the
    dictionary\'s output. Default is `true`.

-   `keepsynonyms` controls whether the synonyms are included in the
    dictionary\'s output. Default is `true`.

-   `rules` is the base name of the file containing the list of
    synonyms. This file must be stored in `$SHAREDIR/tsearch_data/`
    (where `$SHAREDIR` means the PostgreSQL installation\'s shared-data
    directory). Its name must end in `.rules` (which is not to be
    included in the `rules` parameter).

The rules file has the following format:

-   Each line represents a group of synonyms for a single word, which is
    given first on the line. Synonyms are separated by whitespace, thus:

        word syn1 syn2 syn3

-   The sharp (`#`) sign is a comment delimiter. It may appear at any
    position in a line. The rest of the line will be skipped.

Look at `xsyn_sample.rules`, which is installed in
`$SHAREDIR/tsearch_data/`, for an example.

Usage
-----

Installing the `dict_xsyn` extension creates a text search template
`xsyn_template` and a dictionary `xsyn` based on it, with default
parameters. You can alter the parameters, for example

    mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false);
    ALTER TEXT SEARCH DICTIONARY

or create new dictionaries based on the template.

To test the dictionary, you can try

    mydb=# SELECT ts_lexize('xsyn', 'word');
          ts_lexize
    -----------------------
     {syn1,syn2,syn3}

    mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true);
    ALTER TEXT SEARCH DICTIONARY

    mydb=# SELECT ts_lexize('xsyn', 'word');
          ts_lexize
    -----------------------
     {word,syn1,syn2,syn3}

    mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false, MATCHSYNONYMS=true);
    ALTER TEXT SEARCH DICTIONARY

    mydb=# SELECT ts_lexize('xsyn', 'syn1');
          ts_lexize
    -----------------------
     {syn1,syn2,syn3}

    mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true, MATCHORIG=false, KEEPSYNONYMS=false);
    ALTER TEXT SEARCH DICTIONARY

    mydb=# SELECT ts_lexize('xsyn', 'syn1');
          ts_lexize
    -----------------------
     {word}

Real-world usage will involve including it in a text search
configuration as described in [???](#textsearch). That might look like
this:

    ALTER TEXT SEARCH CONFIGURATION english
        ALTER MAPPING FOR word, asciiword WITH xsyn, english_stem;
