org.apache.lucene.search

Class Weight

java.lang.Object

org.apache.lucene.search.Weight

Direct Known Subclasses:

ConstantScoreWeight, DisjunctionMaxQuery.DisjunctionMaxWeight, FilterWeight, SpanWeight

public abstract class Weight
extends Object

Expert: Calculate query weights and build query scorers.

The purpose of Weight is to ensure searching does not modify a Query, so that a Query instance can be reused.
IndexSearcher dependent state of the query should reside in the Weight.
LeafReader dependent state should reside in the Scorer.

Since Weight creates Scorer instances for a given LeafReaderContext (scorer(org.apache.lucene.index.LeafReaderContext)) callers must maintain the relationship between the searcher's top-level IndexReaderContext and the context used to create a Scorer.

A Weight is used in the following way:

1. A Weight is constructed by a top-level query, given a IndexSearcher (Query.createWeight(IndexSearcher, boolean)).
2. The getValueForNormalization() method is called on the Weight to compute the query normalization factor Similarity.queryNorm(float) of the query clauses contained in the query.
3. The query normalization factor is passed to normalize(float, float). At this point the weighting is complete.
4. A Scorer is constructed by scorer(org.apache.lucene.index.LeafReaderContext).

Since:

2.9

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	Weight.DefaultBulkScorer Just wraps a Scorer and performs top scoring using it.

Field Summary

Fields

Modifier and Type	Field and Description
protected Query	parentQuery

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Weight(Query query) Sole constructor, typically invoked by sub-classes.

Method Summary

Modifier and Type	Method and Description
BulkScorer	bulkScorer(LeafReaderContext context) Optional method, to return a BulkScorer to score the query and send hits to a Collector.
abstract Explanation	explain(LeafReaderContext context, int doc) An explanation of the score computation for the named document.
abstract void	extractTerms(Set<Term> terms) Expert: adds all terms occurring in this query to the terms set.
Query	getQuery() The query that this concerns.
abstract float	getValueForNormalization() The value for normalization of contained query clauses (e.g.
abstract void	normalize(float norm, float boost) Assigns the query normalization factor and boost to this.
abstract Scorer	scorer(LeafReaderContext context) Returns a Scorer which can iterate in order over all matching documents and assign them a score.
ScorerSupplier	scorerSupplier(LeafReaderContext context) Optional method.

Methods inherited from class java.lang.Object

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

Field Detail

parentQuery

protected final Query parentQuery

Constructor Detail

Weight

protected Weight(Query query)

Sole constructor, typically invoked by sub-classes.

Parameters:

query - the parent query

Method Detail

extractTerms

public abstract void extractTerms(Set<Term> terms)

Expert: adds all terms occurring in this query to the terms set. If the Weight was created with needsScores == true then this method will only extract terms which are used for scoring, otherwise it will extract all terms which are used for matching.

explain

public abstract Explanation explain(LeafReaderContext context,
                                    int doc)
                             throws IOException

An explanation of the score computation for the named document.

Parameters:

context - the readers context to create the Explanation for.

doc - the document's id relative to the given context's reader

Returns:

an Explanation for the score

Throws:

IOException - if an IOException occurs

getQuery

public final Query getQuery()

The query that this concerns.

getValueForNormalization

public abstract float getValueForNormalization()
                                        throws IOException

The value for normalization of contained query clauses (e.g. sum of squared weights).

Throws:

IOException

normalize

public abstract void normalize(float norm,
                               float boost)

Assigns the query normalization factor and boost to this.

scorer

public abstract Scorer scorer(LeafReaderContext context)
                       throws IOException

Returns a Scorer which can iterate in order over all matching documents and assign them a score.

NOTE: null can be returned if no documents will be scored by this query.

NOTE: The returned Scorer does not have LeafReader.getLiveDocs() applied, they need to be checked on top.

Parameters:

context - the LeafReaderContext for which to return the Scorer.

Returns:

a Scorer which scores documents in/out-of order.

Throws:

IOException - if there is a low-level I/O error

scorerSupplier

public ScorerSupplier scorerSupplier(LeafReaderContext context)
                              throws IOException

Optional method. Get a ScorerSupplier, which allows to know the cost of the Scorer before building it. The default implementation calls scorer(org.apache.lucene.index.LeafReaderContext) and builds a ScorerSupplier wrapper around it.

Throws:

IOException

See Also:

scorer(org.apache.lucene.index.LeafReaderContext)

bulkScorer

public BulkScorer bulkScorer(LeafReaderContext context)
                      throws IOException

Optional method, to return a BulkScorer to score the query and send hits to a Collector. Only queries that have a different top-level approach need to override this; the default implementation pulls a normal Scorer and iterates and collects the resulting hits which are not marked as deleted.

Parameters:

context - the LeafReaderContext for which to return the Scorer.

Returns:

a BulkScorer which scores documents and passes them to a collector.

Throws:

IOException - if there is a low-level I/O error