Package org.apache.lucene.search

Class Weight

java.lang.Object

org.apache.lucene.search.Weight

All Implemented Interfaces:

SegmentCacheable

Direct Known Subclasses:

ConstantScoreWeight, DisjunctionMaxQuery.DisjunctionMaxWeight, FilterWeight, IndriAndWeight, PhraseWeight

public abstract class Weight
extends Object
implements SegmentCacheable

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, ScoreMode, float)).
2. A Scorer is constructed by scorer(org.apache.lucene.index.LeafReaderContext).

Since:

2.9

Nested Class Summary

Nested Classes

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

Field Summary

Fields

Modifier and Type	Field	Description
protected Query	parentQuery

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
BulkScorer	bulkScorer(LeafReaderContext context)	Optional method, to return a BulkScorer to score the query and send hits to a Collector.
int	count(LeafReaderContext context)	Counts the number of live documents that match a given parentQuery in a leaf.
abstract Explanation	explain(LeafReaderContext context, int doc)	An explanation of the score computation for the named document.
Query	getQuery()	The query that this concerns.
Matches	matches(LeafReaderContext context, int doc)	Returns Matches for a specific document, or null if the document does not match the parent query
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

Methods inherited from interface org.apache.lucene.search.SegmentCacheable

isCacheable

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

matches

public Matches matches(LeafReaderContext context,
                       int doc)
                throws IOException

Returns Matches for a specific document, or null if the document does not match the parent query

A query match that contains no position information (for example, a Point or DocValues query) will return MatchesUtils.MATCH_WITH_NO_TERMS

Parameters:

context - the reader's context to create the Matches for

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

Throws:

IOException

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

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.

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

count

public int count(LeafReaderContext context)
          throws IOException

Counts the number of live documents that match a given parentQuery in a leaf.

The default implementation returns -1 for every query. This indicates that the count could not be computed in sub-linear time.

Specific query classes should override it to provide other accurate sub-linear implementations (that actually return the count). Look at MatchAllDocsQuery.createWeight(IndexSearcher, ScoreMode, float) for an example

We use this property of the function to count hits in IndexSearcher.count(Query).

Parameters:

context - the LeafReaderContext for which to return the count.

Returns:

integer count of the number of matches

Throws:

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