# Xapian Spelling Correction

Table of contents

- Introduction
- Algorithm
  - Unicode Support
- QueryParser Integration
- Current Limitations
  - Exactness
  - Backend Support
  - Prefixed Terms
  - Omega
  - QueryParser changed word locations
- References

# Introduction

Xapian provides functionality which can suggest corrections for misspelled words in queries, or in other situations where it might be useful. The suggestions are generated dynamically from the data that has been indexed, so the correction facility isn't tied to particular languages, and it can suggest proper nouns or specialist technical terms.

# Algorithm

A list of candidate words is generated by matching trigrams (groups of 3 adjacent characters) in the candidates against those in the misspelled word. As well as groups of adjacent characters, "starts" and "ends" are generated with the first two and last two characters respectively (e.g. "FISH" generates: "<start>FI", "FIS", "ISH", and "SH<end>").

This technique alone would missing many single-edit errors in two and three character words, so we handle these specially as follows:

For a three character word (e.g. "ABC"), we generate trigrams for the two transposed forms too ("BAC" and "ACB"), in addition to "<start>AB", "ABC", and "BC<end>".

For a two character word (e.g. "AB"), we generate the special start and end trigrams for the reversed form (i.e. "BA"), so the trigrams are "<start>AB", "AB<end>", "<start>BA", and "BA<end>".

And for two, three, and four character words, we generate "bookend" bigrams consisting of the prefix 'B' followed by the first and last letters. This allows us to handle transposition of the middle two characters of a four letter word, substitution or deletion of the middle character of a three letter word, or insertion in the middle of a two letter word.

Note that we don't attempt to suggest corrections for single character words at all, since the suggestions are unlikely to be of good quality (we'd always suggest the same correction for a given database, probably "a" for English). We also don't currently attempt to suggest substitution corrections for two character words, though this would perhaps be useful in some cases.

Those candidates with the better trigram matches are compared to the misspelled word by calculating the "edit distance" - that's the smallest number of operations required to turn one word into another. The allowed operations are: insert a character; delete a character; change a character to another; transpose two adjacent characters. The candidate with the smallest edit distance is found, and if more than one word has the smallest edit distance, that which occurs the most times is chosen. If there's a tie of this too, it's essentially arbitrary which is chosen.

The maximum edit distance to consider can be specified as an optional parameter to Xapian::Database::get_spelling_suggestion(). If not specified, the default is 2, which generally does a good job. 3 is also a reasonable choice in many cases. For most uses, 1 is probably too low, and 4 or more probably too high.

## Unicode Support

Trigrams are generated at the byte level, but the edit distance calculation currently works with Unicode characters, so get_spelling_suggestion() should suggest suitable spelling corrections respecting the specified (or default) edit distance threshold.

# QueryParser Integration

If FLAG_SPELLING_CORRECTION is passed to QueryParser::parse_query() and QueryParser::set_database() has been called, the QueryParser will look for corrections for words in the query which aren't found in the database.

If a correction is found, then a modified version of the query string will be generated which can be obtained by calling QueryParser::get_corrected_query_string(). However, the original query string will still be parsed, since you'll often want to ask the user "Did you mean: [...] ?" - if you want to automatically use the corrected form, just call QueryParser::parse_query() on it.

# Current Limitations

## Exactness

Because Xapian only tests the edit distance for terms which match well (or at all!) on trigrams, it may not always suggest the same answer that would be found if all possible words were checked using the edit distance algorithm. However, the best answer will usually be found, and an exhaustive search would be prohibitively expensive for many uses.

## Backend Support

Currently spelling correction is only supported for flint databases. It works with a single database or multiple databases (use Database::add_database() as usual). We've no plans to support it for the deprecated Quartz backend, nor for InMemory, but we do intend to support it for the remote backend in the future.

## Prefixed Terms

Currently spelling correction ignores prefixed terms.

## Omega

Spelling correction hasn't yet been integrated into Omega.

## QueryParser changed word locations

The QueryParser doesn't currently report the locations of changed words in the query string, so it's a bit fiddly to mark up the altered words specially in HTML output, for example.

# References

The algorithm used to calculate the edit distance is based on that described in the paper "An extension of Ukkonen's enhanced dynamic programming ASM algorithm" by Hal Berghel, University of Arkansas, and David Roach, Acxiom Corporation. It's available online at: http://berghel.net/publications/asm/asm.php