The QueryElevationComponent enables you to configure the top results for a given query regardless of the normal lucene scoring. This is sometimes called "sponsored search", "editorial boosting" or "best bets". This component matches the user query text to a configured Map of top results. Although this component will work with any QueryParser, it makes the most sense to use with DisMax style queries.

Configuration

solrconfig.xml

The query elevation component is configured in solrconfig.xml. A typical configuration may look like:

  <searchComponent name="elevator" class="org.apache.solr.handler.component.QueryElevationComponent" >
    <str name="queryFieldType">string</str>
    <str name="config-file">elevate.xml</str>
  </searchComponent>

  <requestHandler name="/elevate" class="solr.SearchHandler">
    <lst name="defaults">
      <str name="echoParams">explicit</str>
    </lst>
    <arr name="last-components">
      <str>elevator</str>
    </arr>
  </requestHandler>

Available arguments for the searchComponent are:

queryFieldType

Configure which fieldType should be used to analyze the incoming text. For example, it may be appropriate to use a fieldType with a LowerCaseFilter.

config-file

Path to the file that defines query elevation. This file must exist in:

  1. ${instanceDir}/conf/${config-file} , or
  2. ${dataDir}/${config-file}

If the file exists in the /conf/ directory it will be loaded once at start-up. If it exists in the data directory, it will be reloaded for each IndexReader.

forceElevation

By default, this component respects the requested 'sort' parameter -- that is, if the request asks to sort by date, it will order the results by date. If forceElevation=true, results will first return the boosted docs, then order by date.

elevate.xml

Elevated query results are configured in an external .xml file determined by the config-file argument. An elevate.xml file may look like this:

<elevate>

 <query text="AAA">
  <doc id="A" />
  <doc id="B" />
 </query>

 <query text="ipod">
  <doc id="A" />

  <!-- you can optionally exclude documents from a query result -->
  <doc id="B" exclude="true" />
 </query>

</elevate>

For the above configuration, the query "AAA" would first return documents A and B, then whatever normally appears for the same query. For the query "ipod", it would first return A, and would make sure that B is not in the result set.

Note: The uniqueKey field must currently be of type string for the QueryElevationComponent to operate properly.

Usage

All standard solr features such as faceting, sorting, and MoreLikeThis work with this component installed.

enableElevation

For debugging it may be useful to see results with and without the elevated docs. To hide results use "enableElevation=false", like this:

forceElevation

Elevation can also be forced during runtime by adding forceElevation=true to the query URL:

exclusive

Solr 3.x, Solr 4.0: https://issues.apache.org/jira/browse/SOLR-1966

If you want to return only the results specified in the elevation file, add exclusive=true to the URL:

elevateIds/excludeIds

Solr 4.7 https://issues.apache.org/jira/browse/SOLR-5541

You can also directly pass in elevateIds and excludeIds as http parameters. In this scenario the xml config file is bypassed and the documents that are passed in are elevated/excluded. The elevateIds/excludeIds params point to a comma delimitted list of Solr unique doc ID's.

http://localhost:8983/solr/elevate?q=*:*&elevatedIds=doc3,doc4&excludeIds=doc6,doc8

fq

Query elevation respects the standard "filter query" (fq) parameter. That is, if the query contains a fq parameter, all results will be within that filter even if elevate.xml adds other documents to the result set.

Marking Elevated Items in the Results

With Solr4.0, (https://issues.apache.org/jira/browse/SOLR-2037), you can choose to have items that were elevated by this Component "marked" in the output with a pseudo-field by adding in the name of the DocTransformer used as a field list input. The default name for the DocTransformer is "elevated" and it is automatically registered by the QueryElevationComponent. To mark items, simply pass in &fl=[elevated], as in:

...&fl=id,score,[elevated]

with your request.

For instance, in the Solr Example:

http://localhost:8983/solr/elevate?q=ipod&enableElevation=true&fl=id,score,[elevated]

yields:

<response>
 <lst name="responseHeader">
  <int name="status">0</int>
  <int name="QTime">1</int>
  <lst name="params">
   <str name="q">ipod</str>
   <str name="enableElevation">true</str>
   <str name="fl">id,score,[elevated]</str>
  </lst>
 </lst>
 <result name="response" numFound="2" start="0" maxScore="0.73647755">
  <doc>
   <str name="id">MA147LL/A</str>
   <float name="score">0.27617908</float>
   <bool name="[elevated]">true</bool>
  </doc>
  <doc>
   <str name="id">F8V7067-APL-KIT</str>
   <float name="score">0.73647755</float>
   <bool name="[elevated]">false</bool>
  </doc>
 </result>
</response>

Where you can see the [elevated] pseudo-field is set differently for the two items.

If you wish to change the name of the DocTransformer, you can configure the editorialMarkerFieldName initialization argument to the QueryElevationComponent in the solrconfig.xml, as in:

<searchComponent name="elevate" class="org.apache.solr.handler.component.QueryElevationComponent" >
    <str name="queryFieldType">string</str>
    <str name="config-file">elevate.xml</str>
    <str name="editorialMarkerFieldName">foo</str>
</searchComponent>

QueryElevationComponent (last edited 2014-02-19 16:54:35 by JoelBernstein)