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

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.

View this page as Markdown

Cookie settings

Optional tracking stays off until you choose it. Your choice applies to this browser for 180 days. Read the details.

Essential storage keeps you signed in, protects forms, and remembers this choice. It is always available.