# 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:

```json
{
  "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:

```json
{"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](schemas-and-fields.md#variants) and give the plain field a higher weight, or use
  `replace: false` so the exact spelling also matches.
- Encoders are tuned for names. On ordinary text they join unrelated words.
- `beider_morse` handles 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`.
