solr/solr-ref-guide/src/the-query-elevation-component.adoc - lucene-solr - Git at Google

 = The Query Elevation Component
 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
 // distributed with this work for additional information
 // regarding copyright ownership.  The ASF licenses this file
 // to you under the Apache License, Version 2.0 (the
 // "License"); you may not use this file except in compliance
 // with the License.  You may obtain a copy of the License at
 //
 //   http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing,
 // software distributed under the License is distributed on an
 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 // KIND, either express or implied.  See the License for the
 // specific language governing permissions and limitations
 // under the License.

 The Query Elevation Component lets you 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. The text can be any string or non-string IDs, as long as it's indexed. Although this component will work with any QueryParser, it makes the most sense to use with <<the-dismax-query-parser.adoc#,DisMax>> or <<the-extended-dismax-query-parser.adoc#,eDisMax>>.

 The Query Elevation Component also supports distributed searching.

 All of the sample configuration and queries used in this section assume you are running Solr's "```techproducts```" example:

 [source,bash]
 ----
 bin/solr -e techproducts
 ----

 == Configuring the Query Elevation Component

 You can configure the Query Elevation Component in the `solrconfig.xml` file. Search components like `QueryElevationComponent` may be added to any request handler; a dedicated request handler is used here for brevity.

 [source,xml]
 ----
 <searchComponent name="elevator" class="solr.QueryElevationComponent" >
   <!-- pick a fieldType to analyze queries -->
   <str name="queryFieldType">string</str>
   <str name="config-file">elevate.xml</str>
 </searchComponent>

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

 Optionally, in the Query Elevation Component configuration you can also specify the following to distinguish editorial results from "normal" results:

 [source,xml]
 ----
 <str name="editorialMarkerFieldName">foo</str>
 ----

 The Query Elevation Search Component takes the following parameters:

 `queryFieldType`::
 Specifies which field type should be used to analyze the incoming text. For example, it may be appropriate to use a field type with a `LowerCaseFilter`.
 +
 Another example is if you need to unescape backslash-escaped queries, then you can define the field type to preprocess with a `PatternReplaceCharFilter`.
 Here is the corresponding example of field type (traditionally in `managed-schema` or `schema.xml`):
 +
 [source,xml]
 ----
 <fieldType name="unescapelowercase" class="solr.TextField">
   <analyzer>
     <charFilter class="solr.PatternReplaceCharFilterFactory" pattern="\\(.)" replacement="$1"/>
     <tokenizer class="solr.StandardTokenizerFactory"/>
     <filter class="solr.LowerCaseFilterFactory"/>
   </analyzer>
 </fieldType>
 ----
 +
 // NOTE: {IsAlphabetic} and {Digit} below are escaped with '\' so Asciidoctor does not treat them as attributes during conversion to HTML.
 For example, to unescape only non-alphanumeric, the pattern could be `\\([^\p\{IsAlphabetic}\p\{Digit}])`.

 `config-file`::
 Path to the file that defines query elevation. This file must exist in `<instanceDir>/conf/<config-file>` or `<dataDir>/<config-file>`. If the file exists in the `conf/` directory it will be loaded once at startup. If it exists in the `data/` directory, it will be reloaded for each IndexReader.

 `forceElevation`::
 By default, this component respects the requested `sort` parameter: 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. This defaults to `false`.
 This is also a request parameter, which will override the config.

 `useConfiguredElevatedOrder`::
 When multiple docs are elevated, should their relative order be the order in the configuration file or should
 they be subject to whatever the sort criteria is?  True by default.
 This is also a request parameter, which will override the config.
 The effect is most apparent when forceElevation is true and there is sorting on fields.

 `elevateOnlyDocsMatchingQuery`::
 By default, the component will also elevate docs that aren't part of the search result (matching the query).
 If you only want to elevate the docs that are part of the search result, set this to `true` (default is `false`).

 === The elevate.xml File

 Elevated query results can be configured in an external XML file specified in the `config-file` argument. An `elevate.xml` file might look like this:

 [source,xml]
 ----
 <elevate>
   <query text="foo bar">
     <doc id="1" />
     <doc id="2" />
     <doc id="3" />
   </query>

   <query text="ipod">
     <doc id="MA147LL/A" />  <!-- put the actual ipod at the top -->
     <doc id="IW-02" exclude="true" /> <!-- exclude this cable -->
   </query>

   <query text="foo bill" match="subset">
     <doc id="11" />
   </query>
 </elevate>
 ----

 In this example, the query "foo bar" would first return documents 1, 2 and 3, then whatever normally appears for the same query. For the query "ipod", it would first return "MA147LL/A", and would make sure that "IW-02" is not in the result set.

 Notice the `match` parameter with the value `"subset"` for the third rule. A query "bill bar foo" would trigger this rule because the rule defines a subset of terms to appear in the query, in any order. This query would elevate document 11 on top.
 The `match` parameter accepts either `"exact"` (by default) or `"subset"` values.
 Subset matching is scalable, one can add many rules with the `match="subset"` parameter.

 If documents to be elevated are not defined in the `elevate.xml` file, they should be passed in at query time with the <<The elevateIds and excludeIds Parameters,`elevateIds` parameter>>.

 == Using the Query Elevation Component

 === The enableElevation Parameter

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

 [source,text]
 http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&debugQuery=true&enableElevation=true

 [source,text]
 http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&debugQuery=true&enableElevation=false

 === The forceElevation Parameter

 You can force elevation during runtime by adding `forceElevation=true` to the query URL:

 [source,text]
 http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&debugQuery=true&enableElevation=true&forceElevation=true

 === The exclusive Parameter

 You can force Solr to return only the results specified in the elevation file by adding `exclusive=true` to the URL:

 [source,text]
 http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&debugQuery=true&exclusive=true

 === The useConfiguredElevatedOrder Parameter

 You can force set `useConfiguredElevatedOrder` during runtime by supplying it as a request parameter.

 === Document Transformers and the markExcludes Parameter

 The `[elevated]` <<transforming-result-documents.adoc#,Document Transformer>> can be used to annotate each document with information about whether or not it was elevated:

 [source,text]
 http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&fl=id,[elevated]

 Likewise, it can be helpful when troubleshooting to see all matching documents – including documents that the elevation configuration would normally exclude. This is possible by using the `markExcludes=true` parameter, and then using the `[excluded]` transformer:

 [source,text]
 http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&markExcludes=true&fl=id,[elevated],[excluded]

 === The elevateIds and excludeIds Parameters

 When the elevation component is in use, the pre-configured list of elevations for a query can be overridden at request time to use the unique keys specified in these request parameters.

 For example, in the request below documents 3007WFP and 9885A004 will be elevated, and document IW-02 will be excluded -- regardless of what elevations or exclusions are configured for the query "cable" in elevate.xml:

 [source,text]
 http://localhost:8983/solr/techproducts/elevate?q=cable&df=text&excludeIds=IW-02&elevateIds=3007WFP,9885A004

 If either one of these parameters is specified at request time, the entire elevation configuration for the query is ignored.

 For example, in the request below documents IW-02 and F8V7067-APL-KIT will be elevated, and no documents will be excluded – regardless of what elevations or exclusions are configured for the query "ipod" in elevate.xml:

 [source,text]
 http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&elevateIds=IW-02,F8V7067-APL-KIT

 === The fq Parameter with Elevation

 Query elevation respects the standard filter query (`fq`) parameter. That is, if the query contains the `fq` parameter, all results will be within that filter even if `elevate.xml` adds other documents to the result set.
	= The Query Elevation Component
	// Licensed to the Apache Software Foundation (ASF) under one
	// or more contributor license agreements. See the NOTICE file
	// distributed with this work for additional information
	// regarding copyright ownership. The ASF licenses this file
	// to you under the Apache License, Version 2.0 (the
	// "License"); you may not use this file except in compliance
	// with the License. You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing,
	// software distributed under the License is distributed on an
	// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	// KIND, either express or implied. See the License for the
	// specific language governing permissions and limitations
	// under the License.

	The Query Elevation Component lets you 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. The text can be any string or non-string IDs, as long as it's indexed. Although this component will work with any QueryParser, it makes the most sense to use with <<the-dismax-query-parser.adoc#,DisMax>> or <<the-extended-dismax-query-parser.adoc#,eDisMax>>.

	The Query Elevation Component also supports distributed searching.

	All of the sample configuration and queries used in this section assume you are running Solr's "```techproducts```" example:

	[source,bash]
	----
	bin/solr -e techproducts
	----

	== Configuring the Query Elevation Component

	You can configure the Query Elevation Component in the `solrconfig.xml` file. Search components like `QueryElevationComponent` may be added to any request handler; a dedicated request handler is used here for brevity.

	[source,xml]
	----
	<searchComponent name="elevator" class="solr.QueryElevationComponent" >
	<!-- pick a fieldType to analyze queries -->
	<str name="queryFieldType">string</str>
	<str name="config-file">elevate.xml</str>
	</searchComponent>

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

	Optionally, in the Query Elevation Component configuration you can also specify the following to distinguish editorial results from "normal" results:

	[source,xml]
	----
	<str name="editorialMarkerFieldName">foo</str>
	----

	The Query Elevation Search Component takes the following parameters:

	`queryFieldType`::
	Specifies which field type should be used to analyze the incoming text. For example, it may be appropriate to use a field type with a `LowerCaseFilter`.
	+
	Another example is if you need to unescape backslash-escaped queries, then you can define the field type to preprocess with a `PatternReplaceCharFilter`.
	Here is the corresponding example of field type (traditionally in `managed-schema` or `schema.xml`):
	+
	[source,xml]
	----
	<fieldType name="unescapelowercase" class="solr.TextField">
	<analyzer>
	<charFilter class="solr.PatternReplaceCharFilterFactory" pattern="\\(.)" replacement="$1"/>
	<tokenizer class="solr.StandardTokenizerFactory"/>
	<filter class="solr.LowerCaseFilterFactory"/>
	</analyzer>
	</fieldType>
	----
	+
	// NOTE: {IsAlphabetic} and {Digit} below are escaped with '\' so Asciidoctor does not treat them as attributes during conversion to HTML.
	For example, to unescape only non-alphanumeric, the pattern could be `\\([^\p\{IsAlphabetic}\p\{Digit}])`.

	`config-file`::
	Path to the file that defines query elevation. This file must exist in `<instanceDir>/conf/<config-file>` or `<dataDir>/<config-file>`. If the file exists in the `conf/` directory it will be loaded once at startup. If it exists in the `data/` directory, it will be reloaded for each IndexReader.

	`forceElevation`::
	By default, this component respects the requested `sort` parameter: 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. This defaults to `false`.
	This is also a request parameter, which will override the config.

	`useConfiguredElevatedOrder`::
	When multiple docs are elevated, should their relative order be the order in the configuration file or should
	they be subject to whatever the sort criteria is? True by default.
	This is also a request parameter, which will override the config.
	The effect is most apparent when forceElevation is true and there is sorting on fields.

	`elevateOnlyDocsMatchingQuery`::
	By default, the component will also elevate docs that aren't part of the search result (matching the query).
	If you only want to elevate the docs that are part of the search result, set this to `true` (default is `false`).

	=== The elevate.xml File

	Elevated query results can be configured in an external XML file specified in the `config-file` argument. An `elevate.xml` file might look like this:

	[source,xml]
	----
	<elevate>
	<query text="foo bar">
	<doc id="1" />
	<doc id="2" />
	<doc id="3" />
	</query>

	<query text="ipod">
	<doc id="MA147LL/A" /> <!-- put the actual ipod at the top -->
	<doc id="IW-02" exclude="true" /> <!-- exclude this cable -->
	</query>

	<query text="foo bill" match="subset">
	<doc id="11" />
	</query>
	</elevate>
	----

	In this example, the query "foo bar" would first return documents 1, 2 and 3, then whatever normally appears for the same query. For the query "ipod", it would first return "MA147LL/A", and would make sure that "IW-02" is not in the result set.

	Notice the `match` parameter with the value `"subset"` for the third rule. A query "bill bar foo" would trigger this rule because the rule defines a subset of terms to appear in the query, in any order. This query would elevate document 11 on top.
	The `match` parameter accepts either `"exact"` (by default) or `"subset"` values.
	Subset matching is scalable, one can add many rules with the `match="subset"` parameter.

	If documents to be elevated are not defined in the `elevate.xml` file, they should be passed in at query time with the <<The elevateIds and excludeIds Parameters,`elevateIds` parameter>>.

	== Using the Query Elevation Component

	=== The enableElevation Parameter

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

	[source,text]
	http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&debugQuery=true&enableElevation=true

	[source,text]
	http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&debugQuery=true&enableElevation=false

	=== The forceElevation Parameter

	You can force elevation during runtime by adding `forceElevation=true` to the query URL:

	[source,text]
	http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&debugQuery=true&enableElevation=true&forceElevation=true

	=== The exclusive Parameter

	You can force Solr to return only the results specified in the elevation file by adding `exclusive=true` to the URL:

	[source,text]
	http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&debugQuery=true&exclusive=true

	=== The useConfiguredElevatedOrder Parameter

	You can force set `useConfiguredElevatedOrder` during runtime by supplying it as a request parameter.

	=== Document Transformers and the markExcludes Parameter

	The `[elevated]` <<transforming-result-documents.adoc#,Document Transformer>> can be used to annotate each document with information about whether or not it was elevated:

	[source,text]
	http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&fl=id,[elevated]

	Likewise, it can be helpful when troubleshooting to see all matching documents – including documents that the elevation configuration would normally exclude. This is possible by using the `markExcludes=true` parameter, and then using the `[excluded]` transformer:

	[source,text]
	http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&markExcludes=true&fl=id,[elevated],[excluded]

	=== The elevateIds and excludeIds Parameters

	When the elevation component is in use, the pre-configured list of elevations for a query can be overridden at request time to use the unique keys specified in these request parameters.

	For example, in the request below documents 3007WFP and 9885A004 will be elevated, and document IW-02 will be excluded -- regardless of what elevations or exclusions are configured for the query "cable" in elevate.xml:

	[source,text]
	http://localhost:8983/solr/techproducts/elevate?q=cable&df=text&excludeIds=IW-02&elevateIds=3007WFP,9885A004

	If either one of these parameters is specified at request time, the entire elevation configuration for the query is ignored.

	For example, in the request below documents IW-02 and F8V7067-APL-KIT will be elevated, and no documents will be excluded – regardless of what elevations or exclusions are configured for the query "ipod" in elevate.xml:

	[source,text]
	http://localhost:8983/solr/techproducts/elevate?q=ipod&df=text&elevateIds=IW-02,F8V7067-APL-KIT

	=== The fq Parameter with Elevation

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