For AI agents: this page is also available as Markdown at /docs/phonetic-matching.md. Every docs page is: add .md to its URL. llms.txt lists them all.
Phonetic matching
People spell names the way they hear them. The phonetic filter indexes a code for how each word sounds, so names spelled differently but pronounced alike match: Smith and Smyth, Catherine and Kathryn. Keep the original words too, so exact spellings still rank first:
{
"fields": {
"name": {
"type": "text",
"analyzer": {
"tokenizer": "unicode_word",
"filters": ["lowercase", {"name": "phonetic", "params": {"encoder": "double_metaphone", "replace": false}}]
}
}
}
}
| Param | Default | Meaning |
|---|---|---|
encoder | metaphone | The algorithm, see below. |
replace | true | true indexes only the codes; false keeps each word and adds its codes at the same position. |
max_code_len | 4 | Longest code, for double_metaphone only. |
rule_type | approx | beider_morse only: approx or exact. |
name_type | generic | beider_morse only: generic, ashkenazi or sephardic. |
languageset | beider_morse only: the languages of the names, such as ["german", "polish"]. Empty guesses each word's language. |
#Encoders
| Encoder | Suits |
|---|---|
metaphone, double_metaphone | English names and words. Double Metaphone gives a second code for names of other origins, such as Schmidt. |
soundex, refined_soundex | The classic American surname code; refined Soundex separates more sounds. |
caverphone1, caverphone2 | New Zealand English names. |
nysiis | American names, more precise than Soundex. |
cologne | German (Kölner Phonetik). |
daitch_mokotoff | Eastern European and Jewish surnames. |
beider_morse | Names across languages, with the language of each name taken into account. Gives several codes per name. |
Encoder names are case-insensitive, and doubleMetaphone, refinedSoundex, caverphone (the same as caverphone2) and bm work too. A word the encoder cannot handle, such as a number, stays as it is. double_metaphone, daitch_mokotoff and beider_morse can give several codes for one word; they all sit at the word's position.
Beider-Morse with Ashkenazi rules, for a genealogy search:
{"filters": ["lowercase", {"name": "phonetic", "params": {
"encoder": "beider_morse", "name_type": "ashkenazi", "rule_type": "exact"}}]}
#Tips
- Phonetic codes match more than spellings do, so put them in a variant and give the plain field a higher weight, or use
replace: falseso the exact spelling also matches. - Encoders are tuned for names. On ordinary text they join unrelated words.
beider_morsehandles at most 255 characters per word and 256 codes; a longer word is kept as it is.- The encoders are ports of Apache commons-codec, the library behind Elasticsearch's phonetic plugin, and give the same codes.
#Through the compatible APIs
Elasticsearch's phonetic filter (the analysis-phonetic plugin) maps to this filter with its parameters. Its koelnerphonetik encoder maps to cologne with a warning, and haasephonetik is dropped with a warning. Solr's PhoneticFilterFactory, DoubleMetaphoneFilterFactory, BeiderMorseFilterFactory and DaitchMokotoffSoundexFilterFactory map to it too; as in Solr, they keep the original word unless inject is false.