Differences between revisions 40 and 41
Revision 40 as of 2013-04-04 03:33:27
Size: 11574
Comment: Change default value for hl.usePhraseHighlighter to true to match the code.
Revision 41 as of 2017-02-11 06:15:22
Size: 94
Editor: DavidSmiley
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
Solr provides a collection of [[http://lucene.apache.org/solr/api/org/apache/solr/highlight/package-summary.html|highlighting utilities]] which can be reused by various Request Handlers to include "highlighted" matches and snippets in field values. The SearchHandler takes advantage of these via the !HighlightingComponent which support the parameters below.

<<Anchor(HowToOverride)>>Some parameters may be overriden on a per-field basis with the following syntax:

 . `f.<fieldName>.<originalParam>=<value>`

eg. `f.contents.hl.snippets=2`

Since [[Solr3.1]], a termvector-based highlighter called !FastVectorHighlighter can be used. Most of the original Highlighter's parameters make sense for !FastVectorHighlighter, however, some of them don't because of the difference of architecture. Where differences arise, they have been flagged in the descriptions of parameters. If termVectors, termPositions, and termOffsets are on for the field selected in h.fl, !DefaultSolrHighlighter uses !FastVectorHighlighter if the hl.useFastVectorHighlighter parameter set to on. See the {{{hl.useFastVectorHighlighter}}} parameter below for additional details.

See also http://wiki.apache.org/solr/SolrConfigXml#The_Highlighter_plugin_configuration_section

<<TableOfContents>>

== hl ==
Set to "`true`" enable highlighted snippets to be generated in the query response. Any blank or missing value, or "`false`" will disable highlighting.

The default value is blank.

== hl.q ==
Set a query request to be highlighted. It overrides q parameter for highlighting. [[SolrQuerySyntax|Solr query syntax]] is acceptable for this parameter. <!> [[Solr3.5]]

== hl.fl ==
A comma- or space- delimited list of fields for which to generate highlighted snippets. If left blank, the fields highlighted for the LuceneQParser are the defaultSearchField (or the `df` param if used) and for the DisMax parser the `qf` fields are used.

A '*' can be used to match field globs, e.g. 'text_*' or even '*' to highlight on all fields where highlighting is possible. When using '*', consider adding hl.requireFieldMatch=true.

The default value is blank.

== hl.snippets ==
The maximum number of highlighted snippets to generate per field. Note: it is possible for any number of snippets from zero to this value to be generated. This parameter accepts per-field [[#HowToOverride|overrides]].

The default value is "`1`".

== hl.fragsize ==
The size, in characters, of the snippets (aka fragments) created by the highlighter. In the original Highlighter, "`0`" indicates that the whole field value should be used with no fragmenting. With the FastVectorHighlighter, this can be accomplished by adding the following to your configuration:

{{{
<fragListBuilder name="single" class="solr.highlight.SingleFragListBuilder"/>
}}}
And then setting fragListBuilder=single.

This parameter accepts per-field overrides.

The default value is "`100`".

With the original Highlighter, if you have a use case where you need to highlight the complete text of a field and need to highlight every instance of the search term(s) you can set hl.fragsize to a very high value (whatever it takes to include all the text for the largest value for that field), for example &hl.fragsize=50000.

However, if you want to change fragsize to a value greater than 51200 to return long document texts with highlighting, you will need to pass the same value to hl.maxAnalyzedChars parameter too. These two parameters go hand in hand and changing just the hl.fragsize would not be sufficient for highlighting in very large fields.

== hl.mergeContiguous ==
Collapse contiguous fragments into a single fragment. "`true`" indicates contiguous fragments will be collapsed into single fragment. This parameter accepts per-field overrides. This parameter makes sense for the original Highlighter only.

The default value is "`false`", which is also the backward-compatible setting. <!> [[Solr1.3]].

== hl.requireFieldMatch ==
If `true`, then a field will only be highlighted if the query matched in this particular field (normally, terms are highlighted in all requested fields regardless of which field matched the query). This only takes effect if "`hl.usePhraseHighlighter`" is "`true`".

The default value is "`false`".

== hl.maxAnalyzedChars ==
How many characters into a document to look for suitable snippets <!> [[Solr1.3]]. This parameter makes sense for the original Highlighter only.

The default value is "`51200`".

You can assign a large value to this parameter and use hl.fragsize=0 to return highlighting in large fields that have size greater than 51200 characters.

== hl.alternateField ==
If a snippet cannot be generated (due to no terms matching), you can specify a field to use as the fallback. This parameter accepts per-field overrides <!> [[Solr1.3]].

The default value is to not have a default summary.

== hl.maxAlternateFieldLength ==
If `hl.alternateField` is specified, this parameter specifies the maximum number of characters of the field to return <!> [[Solr1.3]]. Any value less than or equal to `0` means unlimited.

The default value is unlimited.

== hl.preserveMulti ==
Preserve order of values in a multiValued list.

default: false.

== hl.maxMultiValuedToExamine ==
When highlighting a multiValued field, stop examining the individual entries after looking at this many of them. Will potentially return 0 snippets if this limit is reached before any snippets are found. If maxMultiValuedToMatch is also specified, whichever limit is hit first will terminate looking for more.

default: Integer.MAX_VALUE

[[Solr4.3]]

== hl.maxMultiValuedToMatch ==
When highlighting a multiValued field, stop examining the individual entries after looking at this many matches are found. If maxMultiValuedToExamine is also specified, whichever limit is hit first will terminate looking for more.

default: Integer.MAX_VALUE

[[Solr4.3]]

== hl.formatter ==
Specify a formatter for the highlight output. Currently the only legal value is "`simple`", which surrounds a highlighted term with a customizable pre- and post text snippet. This parameter accepts per-field overrides. This parameter makes sense for the original Highlighter only.

The default value is "`simple`".

== hl.simple.pre/hl.simple.post ==
The text which appears before and after a highlighted term when using the `simple` formatter. This parameter accepts per-field overrides.

The default values are "`<em>`" and "`</em>`" This parameter makes sense for the original Highlighter only. Use hl.tag.pre and hl.tag.post for FastVectorHighlighter (see example under hl.fragmentsBuilder)

== hl.fragmenter ==
Specify a text snippet generator for highlighted text. The standard fragmenter is `gap` (which is so called because it creates fixed-sized fragments with gaps for multi-valued fields). Another option is `regex`, which tries to create fragments that "look like" a certain regular expression. This parameter accepts per-field overrides. <!> [[Solr1.3]] This parameter makes sense for the original Highlighter only.

The default value is "`gap`"

== hl.fragListBuilder ==
Specify the name of SolrFragListBuilder. <!> [[Solr3.1]] This parameter makes sense for FastVectorHighlighter only. To create a fragSize=0 with the FastVectorHighlighter, use the SingleFragListBuilder.

This field supports per-field overrides.

== hl.fragmentsBuilder ==
Specify the name of SolrFragmentsBuilder. <!> [[Solr3.1]] This parameter makes sense for FastVectorHighlighter only.

SolrFragmentsBuilder respects hl.tag.pre/post parameters:

{{{
<!-- multi-colored tag FragmentsBuilder -->
<fragmentsBuilder name="colored" class="org.apache.solr.highlight.ScoreOrderFragmentsBuilder">
  <lst name="defaults">
    <str name="hl.tag.pre"><![CDATA[
         <b style="background:yellow">,<b style="background:lawgreen">,
         <b style="background:aquamarine">,<b style="background:magenta">,
         <b style="background:palegreen">,<b style="background:coral">,
         <b style="background:wheat">,<b style="background:khaki">,
         <b style="background:lime">,<b style="background:deepskyblue">]]></str>
    <str name="hl.tag.post"><![CDATA[</b>]]></str>
  </lst>
</fragmentsBuilder>
}}}
== hl.boundaryScanner ==
Configures how the boundaries of fragments are determined. By default, boundaries will split at the character level, creating a fragment such as "uick brown fox jumps over the la". Valid entries are breakIterator or simple, with breakIterator being the most commonly used. <!> [[Solr3.5]] This parameter makes sense for FastVectorHighlighter only.

=== hl.bs.maxScan ===
Specify the length of characters to be scanned by SimpleBoundaryScanner. default is 10. <!> [[Solr3.5]] This parameter makes sense for FastVectorHighlighter only.

=== hl.bs.chars ===
Specify the boundary characters, used by SimpleBoundaryScanner. default is ".,!?\t\n" and space. <!> [[Solr3.5]] This parameter makes sense for FastVectorHighlighter only.

=== hl.bs.type ===
Specify one of CHARACTER, WORD, SENTENCE and LINE, used by BreakIteratorBoundaryScanner. default is WORD. <!> [[Solr3.5]] This parameter makes sense for FastVectorHighlighter only.

=== hl.bs.language ===
Specify the language for Locale that is used by BreakIteratorBoundaryScanner. <!> [[Solr3.5]] This parameter makes sense for FastVectorHighlighter only. Valid entries take the form of [[http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes|ISO 639-1]] strings.

=== hl.bs.country ===
Specify the country for Locale that is used by BreakIteratorBoundaryScanner. <!> [[Solr3.5]] This parameter makes sense for FastVectorHighlighter only. Valid entries take the form of [[http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2|ISO 3166-1 alpha-2]] strings.

== hl.useFastVectorHighlighter ==
Use FastVectorHighlighter. FastVectorHighlighter requires the field is termVectors=on, termPositions=on and termOffsets=on. This parameter accepts per-field overrides. <!> [[Solr3.1]]

The default value is "`false`"

== hl.usePhraseHighlighter ==
Use !SpanScorer to highlight phrase terms only when they appear within the query phrase in the document. Default is true. <!> [[Solr1.3]].

== hl.highlightMultiTerm ==
If the !SpanScorer is also being used, enables highlighting for range/wildcard/fuzzy/prefix queries. Default is false. <!> [[Solr1.4]]. This parameter makes sense for the original Highlighter only.

== hl.regex.slop ==
Factor by which the regex fragmenter can stray from the ideal fragment size (given by `hl.fragsize`) to accomodate the regular expression. For instance, a slop of `0.2` with fragsize of `100` should yield fragments between `80` and `120` characters in length. It is usually good to provide a slightly smaller fragsize when using the `regex` fragmenter.

The default value is "`.6`" This parameter makes sense for the original Highlighter only.

== hl.regex.pattern ==
The regular expression for fragmenting. This could be used to extract sentences (see example `solrconfig.xml`) This parameter makes sense for the original Highlighter only.

== hl.regex.maxAnalyzedChars ==
Only analyze this many characters from a field when using the regex fragmenter (after which, the fragmenter produces fixed-sized fragments). Applying a complicated regex to a huge field is expensive.

The default value is "`10000`". This parameter makes sense for the original Highlighter only.
See https://cwiki.apache.org/confluence/display/solr/Highlighting (The Solr Reference Guide)

HighlightingParameters (last edited 2017-02-11 06:15:22 by DavidSmiley)