org.apache.lucene.search.postingshighlight

Class PostingsHighlighter

java.lang.Object

org.apache.lucene.search.postingshighlight.PostingsHighlighter

public final class PostingsHighlighter
extends Object

Simple highlighter that does not analyze fields nor use term vectors. Instead it requires FieldInfo.IndexOptions.DOCS_AND_FREQS_AND_POSITIONS_AND_OFFSETS.

PostingsHighlighter treats the single original document as the whole corpus, and then scores individual passages as if they were documents in this corpus. It uses a BreakIterator to find passages in the text; by default it breaks using getSentenceInstance(Locale.ROOT). It then iterates in parallel (merge sorting by offset) through the positions of all terms from the query, coalescing those hits that occur in a single passage into a Passage, and then scores each Passage using a separate PassageScorer. Passages are finally formatted into highlighted snippets with a PassageFormatter.

WARNING: The code is very new and may still have some exciting bugs!

Example usage:

   // configure field with offsets at index time
   FieldType offsetsType = new FieldType(TextField.TYPE_STORED);
   offsetsType.setIndexOptions(IndexOptions.DOCS_AND_FREQS_AND_POSITIONS_AND_OFFSETS);
   Field body = new Field("body", "foobar", offsetsType);

   // retrieve highlights at query time 
   PostingsHighlighter highlighter = new PostingsHighlighter();
   Query query = new TermQuery(new Term("body", "highlighting"));
   TopDocs topDocs = searcher.search(query, n);
   String highlights[] = highlighter.highlight("body", query, searcher, topDocs);
 

This is thread-safe, and can be used across different readers.

WARNING: This API is experimental and might change in incompatible ways in the next release.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_MAX_LENGTH Default maximum content size to process.

Constructor Summary

Constructors

Constructor and Description
PostingsHighlighter() Creates a new highlighter with default parameters.
PostingsHighlighter(int maxLength) Creates a new highlighter, specifying maximum content length.
PostingsHighlighter(int maxLength, BreakIterator breakIterator, PassageScorer scorer, PassageFormatter formatter) Creates a new highlighter with custom parameters.

Method Summary

Methods

Modifier and Type	Method and Description
String[]	highlight(String field, Query query, IndexSearcher searcher, TopDocs topDocs) Highlights the top passages from a single field.
String[]	highlight(String field, Query query, IndexSearcher searcher, TopDocs topDocs, int maxPassages) Highlights the top-N passages from a single field.
Map<String,String[]>	highlightFields(String[] fields, Query query, IndexSearcher searcher, TopDocs topDocs) Highlights the top passages from multiple fields.
Map<String,String[]>	highlightFields(String[] fields, Query query, IndexSearcher searcher, TopDocs topDocs, int maxPassages) Highlights the top-N passages from multiple fields.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_MAX_LENGTH

public static final int DEFAULT_MAX_LENGTH

Default maximum content size to process. Typically snippets closer to the beginning of the document better summarize its content

See Also:

Constant Field Values

Constructor Detail

PostingsHighlighter

public PostingsHighlighter()

Creates a new highlighter with default parameters.

PostingsHighlighter

public PostingsHighlighter(int maxLength)

Creates a new highlighter, specifying maximum content length.

Parameters:

maxLength - maximum content size to process.

Throws:

IllegalArgumentException - if maxLength is negative or Integer.MAX_VALUE

PostingsHighlighter

public PostingsHighlighter(int maxLength,
                   BreakIterator breakIterator,
                   PassageScorer scorer,
                   PassageFormatter formatter)

Creates a new highlighter with custom parameters.

Parameters:

maxLength - maximum content size to process.

breakIterator - used for finding passage boundaries.

scorer - used for ranking passages.

formatter - used for formatting passages into highlighted snippets.

Throws:

IllegalArgumentException - if maxLength is negative or Integer.MAX_VALUE

Method Detail

highlight

public String[] highlight(String field,
                 Query query,
                 IndexSearcher searcher,
                 TopDocs topDocs)
                   throws IOException

Highlights the top passages from a single field.

Parameters:

field - field name to highlight. Must have a stored string value and also be indexed with offsets.

query - query to highlight.

searcher - searcher that was previously used to execute the query.

topDocs - TopDocs containing the summary result documents to highlight.

Returns:

Array of formatted snippets corresponding to the documents in topDocs. If no highlights were found for a document, its value is null.

Throws:

IOException - if an I/O error occurred during processing

IllegalArgumentException - if field was indexed without FieldInfo.IndexOptions.DOCS_AND_FREQS_AND_POSITIONS_AND_OFFSETS

highlight

public String[] highlight(String field,
                 Query query,
                 IndexSearcher searcher,
                 TopDocs topDocs,
                 int maxPassages)
                   throws IOException

Highlights the top-N passages from a single field.

Parameters:

field - field name to highlight. Must have a stored string value and also be indexed with offsets.

query - query to highlight.

searcher - searcher that was previously used to execute the query.

topDocs - TopDocs containing the summary result documents to highlight.

maxPassages - The maximum number of top-N ranked passages used to form the highlighted snippets.

Returns:

Array of formatted snippets corresponding to the documents in topDocs. If no highlights were found for a document, its value is null.

Throws:

IOException - if an I/O error occurred during processing

IllegalArgumentException - if field was indexed without FieldInfo.IndexOptions.DOCS_AND_FREQS_AND_POSITIONS_AND_OFFSETS

highlightFields

public Map<String,String[]> highlightFields(String[] fields,
                                   Query query,
                                   IndexSearcher searcher,
                                   TopDocs topDocs)
                                     throws IOException

Highlights the top passages from multiple fields.

Conceptually, this behaves as a more efficient form of:

 Map m = new HashMap();
 for (String field : fields) {
   m.put(field, highlight(field, query, searcher, topDocs));
 }
 return m;
 

Parameters:

fields - field names to highlight. Must have a stored string value and also be indexed with offsets.

query - query to highlight.

searcher - searcher that was previously used to execute the query.

topDocs - TopDocs containing the summary result documents to highlight.

Returns:

Map keyed on field name, containing the array of formatted snippets corresponding to the documents in topDocs. If no highlights were found for a document, its value is null.

Throws:

IOException - if an I/O error occurred during processing

IllegalArgumentException - if field was indexed without FieldInfo.IndexOptions.DOCS_AND_FREQS_AND_POSITIONS_AND_OFFSETS

highlightFields

public Map<String,String[]> highlightFields(String[] fields,
                                   Query query,
                                   IndexSearcher searcher,
                                   TopDocs topDocs,
                                   int maxPassages)
                                     throws IOException

Highlights the top-N passages from multiple fields.

Conceptually, this behaves as a more efficient form of:

 Map m = new HashMap();
 for (String field : fields) {
   m.put(field, highlight(field, query, searcher, topDocs, maxPassages));
 }
 return m;
 

Parameters:

fields - field names to highlight. Must have a stored string value and also be indexed with offsets.

query - query to highlight.

searcher - searcher that was previously used to execute the query.

topDocs - TopDocs containing the summary result documents to highlight.

maxPassages - The maximum number of top-N ranked passages per-field used to form the highlighted snippets.

Returns:

Map keyed on field name, containing the array of formatted snippets corresponding to the documents in topDocs. If no highlights were found for a document, its value is null.

Throws:

IOException - if an I/O error occurred during processing

IllegalArgumentException - if field was indexed without FieldInfo.IndexOptions.DOCS_AND_FREQS_AND_POSITIONS_AND_OFFSETS