{{Note|This page describes the solr 3.5 integration which is planned for smila 1.1.<br/>
There will be some breaking changes in regard to how the search record is used and also API changes of the respective bundles. <br/>
The code is developed not @ eclipse as the CQs for solr 3.5 are not yet approved. Once that is the case code will move into eclipse SVN.}}

Solr is an open source search server based on the Lucene search engine. In addition to a powerful full-text-search, sorting and filtering, Solr comes with a lot of built-in features like highlighting, facets, auto-suggest and spell checking.


= SolrServerManager & SolrProperties =
Solr can run as stand alone remote server as well as embedded server within SMILA. There exist a properties file to control the running mode: <tt>configuration/org.eclipse.smila.solr/solr.properties</tt>

<source lang="text">
##### If true SMILA load default configuration for an embedded Solr instance (see below) #####
solr.embedded=true

##### Alternative workspace folder equals solr.home (embedded only) #####
solr.workspaceFolder=./workspace/.metadata/.plugins/org.eclipse.smila.solr

##### Server url for http connections to Solr server (remote only) #####
solr.serverUrl=http://localhost:8983/solr
</source>

= Configuration =

SMILA supports Solr only in multicore setup ("core" is the solr word for a search index), regardless whether Solr runs embedded or remote. 

== DefaultCore ==

The default configuration included in SMILA is defined in <tt>configuration/org.eclipse.smila.solr</tt>. The default mode is 'embedded' in which case SMILA starts up its own internal solr server. The full solr multicore configuration which is present in the configuration folder is used when the mode is set to {{code|embedded}}. This setup defines the sole DefaultCore holding that is suitable for the HowTo cases in SMILA.

If SMILA should connect to an already running Solr server instead of starting up an own instance, the property {{code|solr.embedded}} must be set to {{code|false}}. In that case the URL to connect to the (external) Solr server URL has to be provided by setting the property {{code|solr.serverUrl}} in the properties file.

Please note that you have to add the <tt>PingRequestHandler</tt> in each cores <tt>solrconfig.xml</tt> file, see [[#solrconfig.xml|section solrconfig.xml]]

More information about solr cores and their configuration can be found at: http://wiki.apache.org/solr/CoreAdmin

If SMILA starts up for the first time and Solr is configured embedded, the configuration is copied to Solr workspace (solr.home). 

=== schema.xml ===
One of the most import configuration files is <tt>configuration/org.eclipse.smila.solr/DefaultCore/conf/schema.xml</tt>. This file defines index fields and types. SMILA comes with the following set of predefined fields:

<source lang="xml">
<field name="Id" type="string_id" indexed="true" stored="true" required="true" />
<field name="LastModifiedDate" type="date" indexed="true" stored="true" />
<field name="Filename" type="text_path" indexed="true" stored="true" termVectors="true" termPositions="true" termOffsets="true" />
<field name="Path" type="text_path" indexed="true" stored="true" termVectors="true" termPositions="true" termOffsets="true" />
<field name="Extension" type="textgen" indexed="true" stored="true" />
<field name="Size" type="long" indexed="true" stored="true" />
<field name="MimeType" type="textgen" indexed="true" stored="true" />
<field name="Content" type="textgen" indexed="true" stored="true" termVectors="true" termPositions="true" termOffsets="true" />
<field name="Title" type="textgen" indexed="true" stored="true" termVectors="true" termPositions="true" termOffsets="true" />
<field name="spell" type="textSpell" indexed="true" stored="true" multiValued="true" />
</source>

The schema.xml also contains the '''uniqueKey''' property which Solr needs to know what field is used to id the documents and transparently handles add/updated accordingly. By default it is set to '''Id'''.

Information about other configuration possibilities like field types, default search field, copy fields and many more can be found here: http://wiki.apache.org/solr/SchemaXml

=== solrconfig.xml ===
Another major configuration file is <tt>configuration/org.eclipse.smila.solr/DefaultCore/conf/solfconfig.xml</tt>. This is the configuration for all SearchComponents, RequestHandlers and the general indexing and query configuration.

Please refer to its documentation here: http://wiki.apache.org/solr/SolrConfigXml

Important for SMILA is that in the embedded case the '''dataDir''' property defaults to the data/ sub folder of the core instance (e.i. <tt>solr.home/DefaultCore/data/</tt>. Hence, in embedded mode the SMILA workspace may grow quite large. Use this property in this file or set it through solr.xml at the core to provide an alternative location.

SMILA uses '''autoCommit''' via solr.DirectUpdateHandler2. It tells Solr to commit automatically every 60 seconds or after 1000 documents were added. If this property is not set, no commit will occur and the indexed data will not be persistent or search-able unless you send appropriate solr commands yourself. The values are a compromise where these factors play a role:
* how soon shall/must a user that searches see the updates?
* how many update request are sent to solr?

Note, that during commit the solr server stalls updates which might lead to index pipelet timeouts.

Note that when using an external Solr server, you have to add the PingRequestHandler since this handler is required by the SolrAdminHttpHandler to check if the cores exist and are alive before adressing them. You have to add the handler to each core's configuration file:

<source lang="xml">
<requestHandler name="/admin/ping" class="PingRequestHandler">
  <lst name="defaults">
    <str name="qt">standard</str>
    <str name="q">solrpingquery</str>
    <str name="echoParams">all</str>
  </lst>
</requestHandler>
</source>

== Setup another core ==

If you don't want to use the default solr index (<tt>DefaultCore</tt>), you can easily setup your own core. Just copy the <tt>DefaultCore</tt> configuration (see <tt>SMILA/configuration/org.eclipse.smila.solr</tt>) with another name, e.g. <tt>MyCore</tt>, in the same directory and adapt the configuration files described before to your needs.

Afterwards add your new core to the file <tt>SMILA.application/configuration/org.eclipse.smila.solr/solr.xml</tt>:

<source lang="xml">
<?xml version='1.0' encoding='UTF-8'?>
 <solr persistent="true">
  <cores adminPath="/admin/cores">
   <core name="DefaultCore" instanceDir="DefaultCore"/>
   <core name="MyCore" instanceDir="MyCore"/>
  </cores>
 </solr>
</source>

= How to use Solr with SMILA =

== Indexing data ==

The SolrIndexPipelet can add, update or delete records (equates to Solr documents) in an index.

Configuration in addpipeline:

<source lang="xml">
  <extensionActivity>
      <proc:invokePipelet name="SolrIndexPipelet">
        <proc:pipelet class="org.eclipse.smila.solr.index.SolrIndexPipelet" />
        <proc:variables input="request" output="request" />
        <proc:configuration>
          <!-- either ADD or DELETE. -->
          <rec:Val key="ExecutionMode">ADD</rec:Val>
          <!-- defines the default core into which the record will be written. optional, but if missing then the target core 
            must be set in the record via SolrConstants.DYNAMIC_TARGET_CORE -->
          <rec:Val key="CoreName">DefaultCore</rec:Val>
          <!-- seq of fields that are to be filled. each tuple is a map that defines the target core field, the source field 
            (optional) and the source type (optional ) -->
          <rec:Seq key="CoreFields">
            <rec:Map>
              <!-- target field name in the solr core -->
              <rec:Val key="FieldName">Folder</rec:Val>
              <!-- name of the source attribute or attachment in the record. optional, defaults to the target field name -->
              <rec:Val key="RecSourceName">Path</rec:Val>
              <!-- either ATTRIBUTE or ATTACHMENT. optional, defaults to ATTIRBUTE. -->
              <rec:Val key="RecSourceType">ATTRIBUTE</rec:Val>
            </rec:Map>
            <rec:Map>
              <rec:Val key="FieldName">Filename</rec:Val>
            </rec:Map>
            ...
          </rec:Seq>
        </proc:configuration>
      </proc:invokePipelet>
    </extensionActivity>
</source>

Configuration in deletepipeline:

<source lang="xml">
  <extensionActivity>
      <proc:invokePipelet name="SolrIndexPipelet">
        <proc:pipelet class="org.eclipse.smila.solr.index.SolrIndexPipelet" />
        <proc:variables input="request" output="request" />
        <proc:configuration>
          <rec:Val key="ExecutionMode">DELETE</rec:Val>
          <rec:Val key="CoreName">DefaultCore</rec:Val>
        </proc:configuration>
      </proc:invokePipelet>
    </extensionActivity>
</source>
    
== Search ==

The SMILA standard search servlet already uses solr to search via the SolrSearchPipelet since SMILA version 1.0. Up to version 0.9 the SMILA standard search servlet used plain lucene search.

== Search Pipelet Config ==
The SolrSearchPipelet offers the possibility to search a Solr index. The pipelet needs only a small configuration without any special parameters.

<source lang="xml">
    <extensionActivity>
      <proc:invokePipelet name="invokeSolrSearchPipelet">
        <proc:pipelet class="org.eclipse.smila.solr.search.SolrSearchPipelet" />
        <proc:variables input="request" output="request" />
        <proc:configuration>
        </proc:configuration>
      </proc:invokePipelet>
    </extensionActivity>
</source>

== Solr Specific Search Record ==

For full feature support an enhanced search record is required. 
This sections will provide both, XML samples on how the features are configured in the search record as well as description on helper classes that are  available from within SMILA. Path notations for the elements in the record just have their key names of the respective elements as the path element and always start from the root; e.g. <tt>_solr.params/highlighting</tt>.

To understand the following section you must know the standard [[SMILA/Documentation/Search#Query_Parameters|SMILA search record]] 

=== Standard Parameters ===

The following SMILA standard query parameters are supported:

* maxcount
* offset
* indexname, this must correspond to an existing solr core name
* resultAttributes
* query


=== Query ===

==== Native String ====

The solr pipelet suports a sole <tt>query</tt> element as a string value, which it passes unaltered to solr. The solr default handler assumes this to be a valid Lucene query string, but ultimately this depends on the configured handler. All escaping needs to be done by the one constructing the search record (Note: There is no need to URL encode it, as this is done internally).

<source lang='xml'>
<Record xmlns="http://www.eclipse.org/SMILA/record" version="2.0">
  <!-- query (q) -->
  <Val key="query">Content:solr Content:eclipse</Val>
  <Val key="maxcount" type="long">3</Val>
  <Val key="offset" type="long">3</Val>  
  <Val key="indexname">wikipedia</Val>
  <Seq key="resultAttributes">
    <Val>Content</Val>
    <Val>Id</Val>
  </Seq>
    ...
<Record>

</source>

The above sample shows a query on the index field <tt>Content</tt> for the string "solr eclipse".

==== Fielded Search ====

SMILA's fielded search is also implemented as of v1.0, so that you may search on distinct fields in the index w/o having to employ the native query format.

<source lang='xml'>
	
<Record>
  <Map key="query">
    <Val key="author">shakespeare</Val>
    <Seq key="title">
      <Val>hamlet</Val>
      <Val>merchant</Val>
    </Seq>
  </Map>
</Record>

</source>

which will be translated to:
<tt>author:shakespeare title:(hamlet merchant)</tt>

How this is interpreted by solr depends on the config in place, e.g. combination of the terms are dependent on the value for <tt>  <solrQueryParser defaultOperator="OR"></solrQueryParser></tt> in the solrschema.xml. 

Note, that the values passed to solr are not escaped or modified in any way. Hence a query for:

<source lang='xml'>
  <Map key="query">
  ...
  <Val key="title">merchant of venice</Val>
  ...
  </Map>

</source>

... will lead to (the likly not intended) <tt>title:merchant of venice</tt>. Which is a search on the field "title" with "merchant" but a search of the other words on the default search field as defined in the schema.xml. 




=== Highlighting ===

Highlighting for Solr deviates from the standard SMILA way to support solr features. The configuration is contained in <tt>_solr.query/highlighting</tt> 
<source lang='xml'>
<Map key="_solr.query">
  ...
  <Seq key="highlighting">
    <Map>
      <Val key="attribute">global.solr.params</Val>
      <Val key="hl" type="boolean">true</Val>
      <!-- list of fields to be highlighted, space delimited -->
      <Val key="hl.fl">Content  Title</Val>
      <Val key="hl.simple.pre">&lt;b&gt;</Val>
      <Val key="hl.simple.post">&lt;/b&gt;</Val>
    </Map>
    <!-- other maps with attribute = field name for per-field configuration -->
  </Seq>
  ...
</Map>

</source>

The configuration can be done globally (applies to all HL fields) as well as per field and are contained in maps that must have an entry <tt>attribute</tt> that either contains the value <tt>golabl.solr.params</tt> which then signifies the the global highlight settings or the name of the attribute/filed that is to be highlight-configured.
The other entries in this map correspond in name and values to the ones solr supports.
See http://wiki.apache.org/solr/HighlightingParameters.

In order to turn on highlighting, at least the global config must be present with the entry <tt>hl=true</tt>.

Programmatic highlighting configuration is done though <tt>HihglightingQueryConfigAdapter</tt>. The default constructor creates a configuration object with global highlighting parameters which is required to enable highlighting. The other constructor provides an optional per-field configuration.

<source lang="java">
   // create global highlighting configuration (required, enables highlighting)
    final HighlightingQueryConfigAdapter highlighting = new HighlightingQueryConfigAdapter();
    highlighting.setHighlightingFields("Content Title");
    highlighting.setHighlightingSimplePre("<b>");
    highlighting.setHighlightingSimplePost("</b>");
    builder.addHighlightingConfiguration(highlighting);
</source>

Other than in SMILA, the <tt>_highlight</tt> annotation is not created per result item but replaces the normally returned field value, i.e. when you have the <tt>Content</tt> field to be returned in your search and you also configured highlighting on it, then the search returns only the highlighted value for the <tt>Content</tt> field.

=== Filters ===

Filters are supported the normal way. However, these extensions exist:

* It is also possible to specify an fq parameter natively via <tt>_solr.query</tt>.
* grouping
* tagging
 
==== Grouping ====
In solr you can have many fq parameters which are ANDed in the end. However, it makes a difference from a performance point of view when several smaller filters are combined to a larger one and also there are other things that can be done with one fq, such as local params.  Hence, you may specify a <tt>filterGroup</tt> parameter to assign a particular smila filter to that group. All filters of that group become a single fq parameter where all parts are ANDed, i.e. in lucene syntax: <tt>+(${group1})+(${group2})+...+(${groupN})</tt>

<source lang="xml">
<Seq key="filter">
  <Map>
    <Val key="attribute">author</Val>
    <Seq key="oneOf">
      <Val>pratchett</Val>
      <Val>adams</Val>
    </Seq>
    <Val key="filterGroup">fq1</Val>
  </Map>
</Seq>
</source>

Special behaviors:
* if the group name is missing, then it defaults to the attribute name, resulting in one fq parameter per attribute 
* if the group name is <tt>q</tt> then it will be added to the main query parameter <tt>q</tt>.

Specifying local parameters (and possibly other options in the future) for the group is done like so: 

<source lang="xml">
  ...
  <Map key="_solr.query">
    <Map key="filterGroups">
      <Map key='${groupName}'>
        <Map key='localParameters'>
          <Val key=q.op>AND</Val>
        </Map>
      </Map>
    </Map>
    ...
  </Map>
  ...
</source>   
 
Because the filter group name <tt>q</tt> always denotes the main query parameter, it is possible to specify local parameters for <tt>q</tt> as well through this config.

Note, it is not neccessary to declare filter groups in this section unless you want to specify other parameter than a tag (see below) 

==== Tagging ====

By default filters are not tagged if they dont belong to a group. To add a tag name you must assign a group name. If a filter has a group name, then the fq's tag name is <tt>filterTag_${groupName}</tt> by default but may be overridden in the <tt>filterGroups </tt> config.

{TODO @PW do you like this?}

=== Facets ===

Facets are specified for solr through the <tt>/facetby</tt> Seq as defined in the standard. However, the following differences exist:
* maxcount is optional to allow for solr default configs to work.
* solr doesn't support ordering of facets, so if this is set, then there is a warning in the log but otherwise ignored. 

Faceting is turned on as soon as the <tt>facetby</tt> Seq is present.

Note, that the attibute value must be the solr field-name as the mapping from the solrSearchPipelet is not applied (yet).   

The values in the <tt>nativeParameters</tt> Map are passed to solr for the field verbatim after the pattern <tt>f.${attribute}.${key}=${value}</tt>. This allows you to just specify any valid solr parameter/value pair on field level without any interaction on our part. 
Global facet parameters may be defined in the <tt>_solr.query</tt> map.  

Solr supports different kinds of faceting and this can be selected with the <tt>type</tt> parameter. It's value is solr's respective parameter name and is passed as given. No checks are performed here as to allow future methods OOB. However, it defaults to <tt>facet.field</tt> if missing. Solr's <tt>facet.query</tt> is not supported thru this structure ATM as it needs to be formulated quite differently and hence must be formulated as global parameters in the <tt>_solr.query</tt> map.   

<source lang='xml'>
<Seq key="facetby">
  <!-- per-field configuration for facet.field -->
  <Map>
    <Val key="type">facet.field</Val>
    <Val key="maxcount" type="long">10</Val>
    <Val key="attribute">Extension</Val>
  </Map>
  <!-- per-field configuration for facet.date -->
  <Map>
    <Val key="type">facet.date</Val>
    <Val key="attribute">LastModifiedDate</Val>
    <Map key="nativeParameters">
      <Val key="facet.date.start">NOW/DAY-5DAYS</Val>
      <Val key="facet.date.gap">+1DAY</Val>
      <Val key="facet.date.end">NOW/DAY+1DAY</Val>
    </Map>
  </Map>
</Seq>
</source>

Facets are returned the SMILA standard way in the <tt>facets</tt> map.

==== Naming Facets ====

{TODO
* facetName defaults to attribute name
* impl: creates an implicit localParams with key=${facetName}
}

==== Filtering on Facets ====

Filtering on sepcific facet values is done by specifying a <tt>oneOf</tt> filter as in the normal filters section and behaves exactly like that, i.e. groupName is also supported.

<source lang='xml'>
<Seq key="facetby">
  <Map>
    <Val key="attribute">Extension</Val>
    <Val key="maxcount" type="long">10</Val>
    <Val key="groupName">commonFilters</Val>
    <Seq key="oneOf">
      <Val>doc</Val>
      <Val>xls</Val>
    </Seq>
  </Map>
</Seq>
</source>

Note: ATM only the <tt>oneOf</tt> filter is supported as we cant think of a use case where u want to filter differently on facets.

The filter specified will be transformed to a solr filter and is tagged automatically with the value <tt>facet_${facetLabel}</tt> unless <tt>groupName</tt> is spec'ed in which case the groupName is used or what ever is spec'ed as the filter-group's tag. 

==== Multi Select ====

To turn this on, just add the flag <tt>multiselect</tt>. The respective local parameters for the facet and filter is done automatically. This cannot be combined with <tt>group</tt> though and will result in an error. (this is due to the fact that multiselect relies on tagging the fq and exluding it form the facet, see [http://wiki.apache.org/solr/SimpleFacetParameters#Multi-Select_Faceting_and_LocalParams])

<Seq key="facetby">
  <Map>
    <Val key="attribute">Extension</Val>
    <Val key="maxcount" type="long">10</Val>
    <Val key="multiselect">true</Val>
    <Seq key="oneOf">
      <Val>doc</Val>
      <Val>xls</Val>
    </Seq>
  </Map>
</Seq>
</source>

==== Other parameters ====
The following common constructs are supported

* local parameters
* native parameters, which are applied on field level

TODO: refactor the common stuff into own sections 

==== Range Facetting for different gap sizes ====

ATM solr doesnt support range queries with different gap sizes [https://issues.apache.org/jira/browse/SOLR-2366]. Until this feature is present in solr, smila defines the following construct to support this case to give an easier construct to the user than the underlying <tt>facet.query</tt>.

<source lang='xml'>
<Map>
  <Val key="facetName">FileSize</Val>
  <Val key="attribute">Size</Val>
  <Val key="multiselect" type='boolean'>true</Val>
  <Val key="type">custom.ranges</Val>
  <Seq key="ranges">
    <Val>[* TO 999]</Val>
    <Val>[1000 TO 9999999]</Val>
    <Val>[9999999 TO *]</Val>
  </Seq>
  <Seq key="oneOf">
    <Val>FileSize_1</Val>
  </Seq>
</Map>
</source>

This construct will be transformed to <tt>facet.query</tt> constructs. In fact, the strings in the ranges Seq are just prefix'ed with the attribute name like so: <tt>facet.query={!key=${groupName}_${range_pos} ex=${groupName}}${attribute}:${range}</tt>, e.g.

<source lang='url'>
&facet.query={!key=FileSize_0 ex=facet_FileSize}Size:[ *        TO  999      ]
&facet.query={!key=FileSize_1 ex=facet_FileSize}Size:[ 1000     TO  9999999  ]
&facet.query={!key=FileSize_2 ex=facet_FileSize}Size:[ 1000000  TO  *        ]
</source>

The result is returned as a normal facet where the facet values are ${groupName}_${range_pos}.  

<source lang='xml'>
<Map key="facets">
  <Seq key="FileSize">
    <Map>
      <Val key="value">FileSize_0</Val>
      <Val key="count" type="long">42</Val>
    </Map>
    <Map>
      <Val key="value">FileSize_1</Val>
      <Val key="count" type="long">21</Val>
    </Map>
    ...
  </Seq>
</Map>
</source>

A filter on a facet value would look like so: <tt>&fq={!tag=${groupName}}${attrinute}:${selectedRange}</tt>, e.g. tt>&fq={!tag=facet_FileSize}Size:[1000 TO 9999999]</tt>.

Notes:
* the local param ex= is only set when multiselect is on in which case groupName is not allowed

=== Solr Specific Parameters (_solr.query) ===

Some configuration deviations from the SMILA standard and other solr specialties are put into a Solr specific <tt>_solr.query</tt> Map element at top level of the search record.

{ TODO: rename this nativeParameters?
pro: generic
con: not possible to run 2 engines side by side
But what to do with/name the symentric _solr.results_ then?

IDEA: 
1. keep the _solr.query name and have the nativeParameters be just that in side it
2. rename to nativeParameters that contains known entries but also another nativeParameters with params passed as-is.
}

The following are supported:
* filters
* shards
* request handler

==== Shards ====
Shards are only supported in remote mode and may be defined through the <tt>_solr.query/shards</tt> Seq.

==== Solr Request Handler ====
To select another solr request handler add the <tt>_solr.query/qt</tt> entry.

The following XML snippet shall illustrate these cases:
 
<source lang="xml">
<Record xmlns="http://www.eclipse.org/SMILA/record" version="2.0">
  ...
  <Map key="_solr.query">
    <!-- filter query (fq) -->
    <Seq key="fq">
      <Val>Size:[500 TO 1000]</Val>
      <Val>Author:"H. Simpson"</Val>
    </Seq>

    <!-- shards -->
    <Seq key="shards">
      <Val>http://localhost:8983/solr</Val>
      <Val>http://remote-server:8983/solr</Val>
    </Seq>

    <!-- request handler (qt) -->
    <Val key="qt">/custom</Val>

</Record>
</source>   

The value give is used verbatim.
 

==== Filter Groups ====

This subject is discussed under Filters. 

=== Auxillary Search Functions ===

==== Auto-suggest/Terms ====

Auto suggest/completion is also done via a search request, albeit a very special, stripped down version, which looks like so in the default setup:

<source lang="xml">
<Record >
  <Map key="_solr.query">
    <Map key="terms">
      <Val key="terms" type="boolean">true</Val>
      <Val key="terms.fl">Content</Val>
      <Val key="terms.prefix">con</Val>
    </Map>
    <Val key="qt">/terms</Val>
  </Map>
</Record>
</source>

The only items present have to be the <tt>terms</tt> map and <tt>qt</tt> entry that needs to be set to an appropriate handler (by default this is /terms). The entries in the <tt>terms</tt> map are passed as is to solr.   
For more information about terms configuration and parameters see http://wiki.apache.org/solr/TermsComponent.

The results are returned in the <tt>_solr.result/terms</tt> map with the key as the actual completed word and its value tells you how many documents in the index contain this word.   

<source lang="xml">
<Record >
  <Seq key="records"></Seq>
  <Val key="runtime" type="long">3</Val>
  <Map key="_solr.result">
    <Map key="terms">
      <Val key="congratulations" type="long">1</Val>
      <Val key="conjugate" type="long">1</Val>
      <Val key="containing" type="long">1</Val>
    </Map>
  </Map>
</Record>
</source>   

In SMILA code this can be done like so:

<source lang="java">
    final TermsQueryConfigAdapter terms = new TermsQueryConfigAdapter(_solrField);
    terms.setTermsPrefix("con");
    _queryBuilder.setTermsConfiguration(terms);
    _queryBuilder.setRequestHandler("/terms");
</source>

==== Spellcheck (Did you mean) ====

SIMLA's default setup has spell checking (Did you mean) for the <tt>Content</tt> field enabled. In most cases it's useful to configure the default request handler to use SpellCheckComponent (solrconfig.xml) and this has been done. Otherwise the correct request handler must be set (solrconfig.xml example: /spell). By default SpellCheckComponent uses a separate index which is created on the fly and updated on every commit. Therefore, to retrieve alternative suggestions for possibly misspelled input words, you just need to add the <tt>spellcheck</tt> map to <tt>_solr.query</tt>: 

<source lang="xml">
  <Map key="_solr.query">
     ....
    <Map key="spellcheck">
      <Val key="spellcheck" type="boolean">true</Val>
      <Val key="spellcheck.count" type="long">5</Val>
      <Val key="spellcheck.extendedResults" type="boolean">true</Val>
      <Val key="spellcheck.collate" type="boolean">true</Val>
    </Map>
  </Map>
</source>

The map contains solr parameters (see http://wiki.apache.org/solr/SpellCheckComponent) that are passed "as is" to solr.

This will add the <tt>spellcheck</tt> map to <tt>_solr.result</tt>: 

<source lang="xml">
  <Map key="_solr.result">
    ...
    <Map key="spellcheck">
      <Map key="rust">
        <Val key="just" type="long">1</Val>
        <Val key="bust" type="long">1</Val>
      </Map>
      <Val key="collation">Content:just</Val>
    </Map>
    ...
  </Map>
</source>

For each misspelled word there is a nested map containing the corrections, where the key is the corrected term and the value is the frequency of the term in the index. The value for the frequency must be turned on via spellcheck.extendedResults and defaults to -1 otherwise.

When <tt>collate</tt> is on then you can also find a full alternative query under the key <tt>collation</tt>.

The code for the above XML snippets has been generated with the following code:

<source lang="java">
    addSolrDoc("1",
      "This is a simple text without real meaning as i dont want to bust my behind for smth. with more sense.");
    addSolrDoc("2", "It is just used for testing.");
    indexAndCommit();

    // setup search
    final SpellCheckQueryConfigAdapter spellcheck = new SpellCheckQueryConfigAdapter();
    spellcheck.setSpellCheckCount(5);
    spellcheck.setSpellCheckExtendedResults(true);
    spellcheck.setSpellCheckCollate(true);
    _queryBuilder.setSpellCheckConfiguration(spellcheck);
    _queryBuilder.setQuery("Content:rust");
</source>

==== More Like This / What's related ====

Solr offers a feature to return ''related''  documents which is called in Solr ''More Like This'' (MLT). There are 2 modes supported:

# return for all items in the SRL the top N related documents, see [http://wiki.apache.org/Solr/MoreLikeThis]
# the other does this ad-hoc for just one document for which it uses an own request handler, see [http://wiki.apache.org/Solr/MoreLikeThisHandler]
It is obvious that the first variant requires much more performance than the 2nd.

Both modes are supported through SMILA and configured very similar. SMILA doesn't do anything special to the arguments you pass in with the record and hands them on to Solr as-is, except that it performes any necessary URL encoding for you. While you may assign specific data types to the parameters, this is not necessary and all values may be given as strings as this is what is being passed on to Solr anyhow.

Which mode is active ultimatly depends on your handler configuration in solrconfig.xml. However, we will assume here SMILA's default setup which binds the MLT handler to <tt>/mlt</tt> and a normal query to <tt>/select</tt>.  

Both modes share most of the MLT parameters but also need/support specific ones.
  
<source lang="xml">
<record>
  
  <!-- this is the lucene query expression that is executed in both cases. -->  
  <Val key="query">euklid</Val>
  ...
  <Map key="_solr.query">
    <!-- this select the solr request handler. set it to /mlt when u want to use the MLT handler  -->  
    <!-- <Val key="qt">/mlt</Val> -->
    <!-- determines the list of fields returned for both the normal results as well as the MLT results  -->  
    <Val key="fl" >Id,score,Size</Val>
    ...
    <Map key="moreLikeThis">
      <Val key="mlt" >true</Val>
      <Val key="mlt.fl" >Content</Val>
      <Val key="mlt.mindf">1</Val>
      <Val key="mlt.mintf">1</Val>
      ...
    </Map>
  </Map>
<record>
</source>


===== MLT Results w/o Handler =====

In this case solr will add the <tt>moreLikeThis</tt> section on the same level as the normal <tt>response</tt> section and you need to manually look up the MLT docs for each given result item. SMILA on the other hand transforms the solr result in that it converts the MLT information as a nested part of SMILA's result item, like so:

<source lang="xml">
<Seq key="records">
  <Map>
    <Val key="_recordid">file:Euklid.html</Val>
    <Val key="_weight" type="double">0.7635468</Val>
    <Map key="_mlt.meta">
      <Val key="start" type="long">0</Val>
      <Val key="count" type="long">3</Val>
      <Val key="max_score" type="double">0.8115930557250977</Val>
    </Map>
    <Seq key='_mlt'>
      <Map>
        <Val key="_recordid">file:Archytas_von_Tarent_7185.html</Val>
        <Val key="_weight" type="double">0.5511907</Val>
        <Val key="Size" type="long">47934</Val>
        ...                
      </Map>
      <Map>
        <Val key="_recordid">file:Aristoxenos.html</Val>
        <Val key="_weight" type="double">0.44604447</Val>
        <Val key="Size" type="long">39332</Val>
        ...                
      </Map>
      ... 
    </Seq>
    ...
  </Map>
   ... 
</Seq>
</source>

This sample contains the Solr result item with the id <tt>file:Euklid.html</tt>. With MLT turned on, it now contains a nested  <tt>_mlt</tt> Seq which holds the N related docs for that result item each represented by a Map (MLT-Map) (yes, this prevents you from having a solr doc field of the same name and have it returned in this MLT mode). The Val elements in each MLT-Map are defined by the list of fields in the <tt>fl</tt> parameter. But how do the <tt>_recordid</tt> and <tt>_weight</tt> VALs get in there if the value is actually <tt>Id,score,Size</tt>? Well, SMILA defines the fields <tt>Id</tt> and <tt>score</tt> and automatically maps them to <tt>_recordid</tt> and <tt>_weight</tt>.  Any other field that you include thru <tt>fl</tt> is added as a Val element to the MLT result item having the same key as the field name, as is shown for ''Size'' here. 
There is also the <tt>_mlt.meta</tt> Map that contains result info regarding the MLT result, such as number of items, start (offset), and max_score. The keys of these values are the same as for the normal result.  

===== MLT Results with Handler =====

The more common use case of MLT is to actually return the related docs for just one document due to performance considerations.  This is done by making a request against the MLT handler itself.

The document for which you want the related docs is usually known, e.g. from a previous search and your rendered result list contains a link to fetch/show related docs. In this case the query just selects the given document by its Id ( as shown in the example below). But you also may provide any other query here. However, if the query returns >1 docs it will select just one depending on the other MLT parameter and return only the related docs for that document.

The differences to the query record above are like so:

<source lang="xml">
<record>
  
  <!-- this is the lucene query to select an document by its Id. Note, the escaping of the ID string! -->  
  <Val key="query">Id:file\:Euklid.html</Val>
  ...
  <Map key="_solr.query">
    <!-- this select the solr MLT request handler. -->  
    <Val key="qt">/mlt</Val>
    ...
  </Map>
<record>
</source>

The results for such an MLT request are contained in the standard <tt>records</tt> Seq the same way that normal search results are returned, except that they signify MLT docs.

<source lang="xml">
<Seq key="records">
  <Map>
    <Val key="_recordid">file:Archytas_von_Tarent_7185.html</Val>
    <Val key="_weight" type="double">0.5511907</Val>
    <Val key="Size" type="long">47934</Val>
  </Map>
  <Map>
    <Val key="_recordid">file:Aristoxenos.html</Val>
    <Val key="_weight" type="double">0.44604447</Val>
    <Val key="Size" type="long">39332</Val>
  </Map>
  ...
</Seq>

</source>

{{note| help wanted |due to lack of need, returning the mlt.interestingTerms has not been impl'ed yet}}

In case of <tt>mlt.interestingTerms=details</tt>  the result record will contain the following additional information:

<source lang="xml">
<Map key="_solr.result">
    ...
    <Map key="interestingTerms">
      <Val key="Content:euklid" type="double">1.0</Val>
      <Val key="Content:geometrie" type="double">1.0</Val>
      ...
    </Map>
    ...
  </Seq>
</Map>
</source>

or in case of <tt>mlt.interestingTerms=list</tt> just:

<source lang="xml">
<Map key="_solr.result">
    ...
    <Seq key="interestingTerms">
      
      <Val>euklid</Val>
      <Val>geometrie</Val>
      ...
    </Map>
    ...
  </Seq>
</Map>
</source>