Assuming your dictionary is going to be based on indexed content instead of a file, a field should be set aside exclusively for this purpose. This is so that it can be analyzed appropriately and so that other fields can be copied into it, as the spellcheckers use just one field. Most Solr setups would have one field; our MusicBrainz searches, on the other hand, are segmented by the data type (artists, releases, and tracks), and so one for each would be best. For the purposes of demonstrating this feature, we will only do it for artists.

In schema.xml, we need to define the field type for spellchecking. This particular configuration is one we recommend for most scenarios:

<fieldType name="textSpell" class="solr.TextField" positionIncrementGap="100" stored="false" multiValued="true">
  <analyzer type="index">
    <tokenizer class="solr.StandardTokenizerFactory"/>
    <filter class="solr.LowerCaseFilterFactory"/>
    <filter class="solr.SynonymFilterFactory" synonyms="synonyms.txt" ignoreCase="true"
            expand="true"/>
    <filter class="solr.StopFilterFactory" ignoreCase="true" words="stopwords.txt"/>
    <filter class="solr.RemoveDuplicatesTokenFilterFactory"/>
  </analyzer>
  <analyzer type="query">
    <tokenizer class="solr.StandardTokenizerFactory"/>
    <filter class="solr.LowerCaseFilterFactory"/>
    <filter class="solr.StopFilterFactory" ignoreCase="true" words="stopwords.txt"/>
    <filter class="solr.RemoveDuplicatesTokenFilterFactory"/>
  </analyzer>
</fieldType>

A field type for spellchecking is not marked as stored because the spellcheck component only uses the indexed terms. The important thing is to ensure that the text analysis does not perform stemming, as the corrections presented would suggest the stems, which would look very odd to the user for most stemmer algorithms. It's also hard to imagine a use case that doesn't apply lowercasing.

Now, we need to create a field for this data:

<field name="a_spell" type="textSpell" />

And we need to get data into it with some copyField directives:

<copyField source="a_name" dest="a_spell" />
<copyField source="a_alias" dest="a_spell" />

Arguably, a_member_name may be an additional choice to copy as well, as the dismax search we configured (seen in the following code) searches it too, albeit at a reduced score. This, as well as many decisions with search configuration, is subjective.

To use any search component, it needs to be in the components list of a request handler. The spellcheck component is not in the standard list, so it needs to be added:

<requestHandler name="/mb_artists" class="solr.SearchHandler">
  <!-- default values for query parameters -->
  <lst name="defaults">
    <str name="defType">edismax</str>
    <str name="qf">a_name a_alias^0.8 a_member_name^0.4</str>
    <!-- etc. -->
  </lst>
  <arr name="last-components">
    <str>spellcheck</str>
  </arr>
</requestHandler>

This component should already be defined in solrconfig.xml. Within the spellchecker search component, there is one or more XML blocks named spellchecker, so that different dictionaries and other options can be configured. These might also be loosely referred to as the dictionaries, because the parameter that refers to this choice is named that way (more on that later). We have two spellcheckers configured as follows:

A complete MusicBrainz implementation would have a different spellchecker for each MB data type, with all of them configured similarly.

Following the excerpt given here is an example configuration of the key options available in the spellchecker component:

<searchComponent name="spellcheck"
    class="solr.SpellCheckComponent">
  <str name="queryAnalyzerFieldType">textSpell</str><!-- 'q'
    only -->

  <lst name="spellchecker">
    <str name="name">a_spell</str>
    <str name="field">a_spell</str>
    <str name="classname">solr.DirectSolrSpellChecker</str>
    <str name="distanceMeasure">internal</str>
    <float name="accuracy">0.5</float>
    <int name="maxEdits">1</int>
    <int name="minPrefix">1</int>
    <int name="maxInspections">5</int>
    <int name="minQueryLength">4</int>
    <float name="maxQueryFrequency">0.01</float>
    <float name="thresholdTokenFrequency">.01</float>
  </lst>
  <!-- just an example -->
  <lst name="spellchecker">
    <str name="name">file</str>
    <str name="classname">solr.FileBasedSpellChecker</str>
    <str name="sourceLocation">spellings.txt</str>
    <str name="characterEncoding">UTF-8</str>
  </lst>
</searchComponent>

If the spellchecker you are using is IndexedBasedSpellChecker or FileBasedSpellChecker (or, technically, Suggester), then it needs to be built, which is the process in which the dictionary is read and is built into the spellcheckIndexDir. If it isn't built, then no corrections will be offered, and you'll probably be very confused. You'll be even more confused when troubleshooting the results if it was built once but is far out of date and so needs to be built again.

Generally, building is required if it has never been built before, and it should be built periodically when the dictionary changes. It need not necessarily be built for every change, but it obviously won't benefit from any such modifications.

In order to perform the build of a spellchecker, simply enable the component with spellcheck=true, add a special parameter called spellcheck.build, and set it to true: http://localhost:8983/solr/mbartists/select?&qt=mb_artists&rows=0&spellcheck=true&spellcheck.build=true&spellcheck.dictionary=a_spell.

The other spellcheck parameters will be explained shortly. There is an additional related option similar to spellcheck.build called spellcheck.reload. This doesn't rebuild the index, but it basically re-establishes connections with the index—both sourceLocation for index-based spellcheckers and spellcheckIndexDir for all types. If you've decided to have some external process build the dictionary or simply share built indexes between spellcheckers, then Solr needs to know to reload it to see the changes—a quick operation.

At this point, we've covered how to configure a spellchecker but not how to issue requests that actually use it. In summary, all that you are required to do is add spellcheck=true to a standard search request, but it is more likely that you will set other options, once you start experimenting.

It's important to be aware that there are effectively three mutually exclusive internal modes that this component places itself in:

Despite these progressively aggressive spellcheck modes, there might still be no suggestions or fewer than the number asked for if it simply can't find anything suitable.

Let's now explore the various request parameters recognized by the spellchecker component:

We'll try out a typical spellcheck configuration that we've named a_spell. We've disabled showing the query results with rows=0 because the actual query results aren't the point of these examples. In this example, it is imagined that the user is searching for the band Smashing Pumpkins, but with a misspelling.

Here are the search results for Smashg Pumpkins, using the a_spell dictionary:

<?xml version="1.0"?>
<response>
<lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">124</int>
    <lst name="params">
    <str name="spellcheck">true</str>
    <str name="indent">on</str>
    <str name="spellcheck.extendedResults">true</str>
    <str name="spellcheck.collateExtendedResults">true</str>
    <str name="spellcheck.maxCollationTries">5</str>
    <str name="spellcheck.collate">true</str>
    <str name="rows">0</str>
    <str name="echoParams">explicit</str>
    <str name="q">Smashg Pumpkins</str>
    <str name="spellcheck.dictionary">a_spell</str>
    <str name="spellcheck.count">5</str>
    <str name="qt">/mb_artists</str>
  </lst>
</lst>
<result name="response" numFound="0" start="0"/>
<lst name="spellcheck">
  <lst name="suggestions">
    <lst name="smashg">
      <int name="numFound">5</int>
      <int name="startOffset">0</int>
      <int name="endOffset">6</int>
      <int name="origFreq">0</int>
      <arr name="suggestion">
        <lst>
          <str name="word">smash</str>
          <int name="freq">36</int>
        </lst>
        <lst>
          <str name="word">smashing</str>
          <int name="freq">4</int>
        </lst>
        <lst>
          <str name="word">smashign</str>
          <int name="freq">1</int>
        </lst>
        <lst>
          <str name="word">smashed</str>
          <int name="freq">5</int>
        </lst>
        <lst>
          <str name="word">smasher</str>
          <int name="freq">2</int>
        </lst>
      </arr>
    </lst>
    <bool name="correctlySpelled">false</bool>
    <lst name="collation">
      <str name="collationQuery">smashing Pumpkins</str>
      <int name="hits">1</int>
      <lst name="misspellingsAndCorrections">
        <str name="smashg">smashing</str>
      </lst>
    </lst>
  </lst>
</lst>
</response>

In this scenario, we intentionally chose a misspelling that is closer to another word: "smash". Were it not for maxCollationTries, the suggested collation would be "smash Pumpkins", which would return no results. There are a few things we want to point out regarding the spellchecker response: