WARNING: The 2.x versions of Elasticsearch have passed their EOL dates. If you are running a 2.x version, we strongly advise you to upgrade.

This documentation is no longer maintained and may be removed. For the latest information, see the current Elasticsearch documentation.

Elasticsearch: The Definitive Guide [2.x] » Dealing with Human Language » Reducing Words to Their Root Form » Hunspell Stemmer
« Dictionary Stemmers Choosing a Stemmer »

Hunspell Stemmeredit

Elasticsearch provides dictionary-based stemming via the hunspell token filter. Hunspell hunspell.github.io is the spell checker used by Open Office, LibreOffice, Chrome, Firefox, Thunderbird, and many other open and closed source projects.

Hunspell dictionaries can be obtained from the following:

A Hunspell dictionary consists of two files with the same base name—​such as en_US—but with one of two extensions:

.dic
Contains all the root words, in alphabetical order, plus a code representing all possible suffixes and prefixes (which collectively are known as affixes)
.aff
Contains the actual prefix or suffix transformation for each code listed in the .dic file

Installing a Dictionaryedit

The Hunspell token filter looks for dictionaries within a dedicated Hunspell directory, which defaults to ./config/hunspell/. The .dic and .aff files should be placed in a subdirectory whose name represents the language or locale of the dictionaries. For instance, we could create a Hunspell stemmer for American English with the following layout:

config/
  └ hunspell/ 
      └ en_US/ 
          ├ en_US.dic
          ├ en_US.aff
          └ settings.yml

The location of the Hunspell directory can be changed by setting indices.analysis.hunspell.dictionary.location in the config/elasticsearch.yml file.

en_US will be the name of the locale or language that we pass to the hunspell token filter.

Per-language settings file, described in the following section.

Per-Language Settingsedit

The settings.yml file contains settings that apply to all of the dictionaries within the language directory, such as these:

---
ignore_case:          true
strict_affix_parsing: true

The meaning of these settings is as follows:

ignore_case

Hunspell dictionaries are case sensitive by default: the surname Booker is a different word from the noun booker, and so should be stemmed differently. It may seem like a good idea to use the hunspell stemmer in case-sensitive mode, but that can complicate things:

  • A word at the beginning of a sentence will be capitalized, and thus appear to be a proper noun.
  • The input text may be all uppercase, in which case almost no words will be found.
  • The user may search for names in all lowercase, in which case no capitalized words will be found.

As a general rule, it is a good idea to set ignore_case to true.

strict_affix_parsing
The quality of dictionaries varies greatly. Some dictionaries that are available online have malformed rules in the .aff file. By default, Lucene will throw an exception if it can’t parse an affix rule. If you need to deal with a broken affix file, you can set strict_affix_parsing to false to tell Lucene to ignore the broken rules.

Custom Dictionaries

If multiple dictionaries (.dic files) are placed in the same directory, they will be merged together at load time. This allows you to tailor the downloaded dictionaries with your own custom word lists:

config/
  └ hunspell/
      └ en_US/  
          ├ en_US.dic
          ├ en_US.aff 
          ├ custom.dic
          └ settings.yml

The custom and en_US dictionaries will be merged.

Multiple .aff files are not allowed, as they could use conflicting rules.

The format of the .dic and .aff files is discussed in Hunspell Dictionary Format.

Creating a Hunspell Token Filteredit

Once your dictionaries are installed on all nodes, you can define a hunspell token filter that uses them:

PUT /my_index
{
  "settings": {
    "analysis": {
      "filter": {
        "en_US": {
          "type":     "hunspell",
          "language": "en_US" 
        }
      },
      "analyzer": {
        "en_US": {
          "tokenizer":  "standard",
          "filter":   [ "lowercase", "en_US" ]
        }
      }
    }
  }
}

The language has the same name as the directory where the dictionary lives.

You can test the new analyzer with the analyze API, and compare its output to that of the english analyzer:

GET /my_index/_analyze?analyzer=en_US 
reorganizes

GET /_analyze?analyzer=english 
reorganizes

Returns organize

Returns reorgan

An interesting property of the hunspell stemmer, as can be seen in the preceding example, is that it can remove prefixes as well as as suffixes. Most algorithmic stemmers remove suffixes only.

Hunspell dictionaries can consume a few megabytes of RAM. Fortunately, Elasticsearch creates only a single instance of a dictionary per node. All shards that use the same Hunspell analyzer share the same instance.

Hunspell Dictionary Formatedit

While it is not necessary to understand the format of a Hunspell dictionary in order to use the hunspell tokenizer, understanding the format will help you write your own custom dictionaries. It is quite simple.

For instance, in the US English dictionary, the en_US.dic file contains an entry for the word analyze, which looks like this:

analyze/ADSG

The en_US.aff file contains the prefix or suffix rules for the A, G, D, and S flags. Each flag consists of a number of rules, only one of which should match. Each rule has the following format:

[type] [flag] [letters to remove] [letters to add] [condition]

For instance, the following is suffix (SFX) rule D. It says that, when a word ends in a consonant (anything but a, e, i, o, or u) followed by a y, it can have the y removed and ied added (for example, ready → readied).

SFX    D      y   ied  [^aeiou]y

The rules for the A, G, D, and S flags mentioned previously are as follows:

SFX D Y 4
SFX D   0     d          e 
SFX D   y     ied        [^aeiou]y
SFX D   0     ed         [^ey]
SFX D   0     ed         [aeiou]y

SFX S Y 4
SFX S   y     ies        [^aeiou]y
SFX S   0     s          [aeiou]y
SFX S   0     es         [sxzh]
SFX S   0     s          [^sxzhy] 

SFX G Y 2
SFX G   e     ing        e 
SFX G   0     ing        [^e]

PFX A Y 1
PFX A   0     re         .

analyze ends in an e, so it can become analyzed by adding a d.

analyze does not end in s, x, z, h, or y, so it can become analyzes by adding an s.

analyze ends in an e, so it can become analyzing by removing the e and adding ing.

The prefix re can be added to form reanalyze. This rule can be combined with the suffix rules to form reanalyzes, reanalyzed, reanalyzing.

More information about the Hunspell syntax can be found on the Hunspell documentation site.

« Dictionary Stemmers Choosing a Stemmer »