java.lang.Object  
↳  org.apache.lucene.search.Similarity 
Known Direct Subclasses 
Expert: Scoring API.
Similarity defines the components of Lucene scoring. Overriding computation of these components is a convenient way to alter Lucene scoring.
Suggested reading: Introduction To Information Retrieval, Chapter 6.
The following describes how Lucene scoring evolves from underlying information retrieval models to (efficient) implementation. We first brief on VSM Score, then derive from it Lucene's Conceptual Scoring Formula, from which, finally, evolves Lucene's Practical Scoring Function (the latter is connected directly with Lucene classes and methods).
Lucene combines Boolean model (BM) of Information Retrieval with Vector Space Model (VSM) of Information Retrieval  documents "approved" by BM are scored by VSM.
In VSM, documents and queries are represented as weighted vectors in a multidimensional space, where each distinct index term is a dimension, and weights are Tfidf values.
VSM does not require weights to be Tfidf values, but Tfidf values are believed to produce search results of high quality, and so Lucene is using Tfidf. Tf and Idf are described in more detail below, but for now, for completion, let's just say that for given term t and document (or query) x, Tf(t,x) varies with the number of occurrences of term t in x (when one increases so does the other) and idf(t) similarly varies with the inverse of the number of index documents containing term t.
VSM score of document d for query q is the
Cosine Similarity
of the weighted query vectors V(q) and V(d):
 

Note: the above equation can be viewed as the dot product of the normalized weighted vectors, in the sense that dividing V(q) by its euclidean norm is normalizing it to a unit vector.
Lucene refines VSM score for both search quality and usability:
Under the simplifying assumption of a single field in the index,
we get Lucene's Conceptual scoring formula:
 

The conceptual formula is a simplification in the sense that (1) terms and documents are fielded and (2) boosts are usually per query term rather than per query.
We now describe how Lucene implements this conceptual scoring formula, and derive from it Lucene's Practical Scoring Function.
For efficient score computation some scoring components are computed and aggregated in advance:
Lucene's Practical Scoring Function is derived from the above. The color codes demonstrate how it relates to those of the conceptual formula:
 

where
DefaultSimilarity
is:
tf(t in d) =

frequency^{½} 
DefaultSimilarity
is:
idf(t) =

1 + log ( 

) 
coord(q,d)
by the Similarity in effect at search time.
DefaultSimilarity
produces a Euclidean norm:
queryNorm(q) =
queryNorm(sumOfSquaredWeights)
=


Weight
object.
For example, a boolean query
computes this value as:
sumOfSquaredWeights =
q.getBoost() ^{2}
·

∑  ( idf(t) · t.getBoost() ) ^{2} 
t in q 
setBoost()
.
Notice that there is really no direct API for accessing a boost of one term in a multi term query,
but rather multi terms are represented in a query as multi
TermQuery
objects,
and so the boost of a term in the query is accessible by calling the subquery
getBoost()
.
doc.setBoost()
before adding the document to the index.
field.setBoost()
before adding the field to a document.
lengthNorm(field)
 computed
when the document is added to the index in accordance with the number of tokens
of this field in the document, so that shorter fields contribute more to the score.
LengthNorm is computed by the Similarity class in effect at indexing.
When a document is added to the index, all the above factors are multiplied.
If the document has multiple fields with the same name, all their boosts are multiplied together:
norm(t,d) =
doc.getBoost()
·
lengthNorm(field)
·

∏ 
f.getBoost ()

field f in d named as t 
encoded
as a single byte
before being stored.
At search time, the norm byte value is read from the index
directory
and
decoded
back to a float norm value.
This encoding/decoding, while reducing index size, comes with the price of
precision loss  it is not guaranteed that decode(encode(x)) = x.
For instance, decode(encode(0.89)) = 0.75.
Similarity
for search.
Constants  

int  NO_DOC_ID_PROVIDED 
Public Constructors  

Public Methods  

Compute the normalization value for a field, given the accumulated
state of term processing for this field (see
FieldInvertState ).  
Computes a score factor based on the fraction of all query terms that a
document contains.
 
Decodes a normalization factor stored in an index.
 
Encodes a normalization factor for storage in an index.
 
Return the default Similarity implementation used by indexing and search
code.
 
Returns a table for decoding normalization bytes.
 
Computes a score factor based on a term's document frequency (the number
of documents which contain the term).
 
Computes a score factor for a phrase.
 
Computes a score factor for a simple term and returns an explanation
for that score factor.
 
Computes the normalization value for a field given the total number of
terms contained in a field.
 
Computes the normalization value for a query given the sum of the squared
weights of each of the query terms.
 
Calculate a scoring factor based on the data in the payload.
 
Set the default Similarity implementation used by indexing and search
code.
 
Computes the amount of a sloppy phrase match, based on an edit distance.
 
Computes a score factor based on a term or phrase's frequency in a
document.
 
Computes a score factor based on a term or phrase's frequency in a
document.

[Expand]
Inherited Methods  

From class
java.lang.Object

Compute the normalization value for a field, given the accumulated
state of term processing for this field (see FieldInvertState
).
Implementations should calculate a float value based on the field state and then return that value.
For backward compatibility this method by default calls
lengthNorm(String, int)
passing
getLength()
as the second argument, and
then multiplies this value by getBoost()
.
WARNING: This API is new and experimental and may suddenly change.
field  field name 

state  current processing state for this field 
Computes a score factor based on the fraction of all query terms that a document contains. This value is multiplied into scores.
The presence of a large portion of the query terms indicates a better match with the query, so implementations of this method usually return larger values when the ratio between these parameters is large and smaller values when the ratio between them is small.
overlap  the number of query terms matched in the document 

maxOverlap  the total number of terms in the query 
Decodes a normalization factor stored in an index.
Encodes a normalization factor for storage in an index.
The encoding uses a threebit mantissa, a fivebit exponent, and the zeroexponent point at 15, thus representing values from around 7x10^9 to 2x10^9 with about one significant decimal digit of accuracy. Zero is also represented. Negative numbers are rounded up to zero. Values too large to represent are rounded down to the largest representable value. Positive values too small to represent are rounded up to the smallest positive representable value.
Return the default Similarity implementation used by indexing and search code.
This is initially an instance of DefaultSimilarity
.
Returns a table for decoding normalization bytes.
Computes a score factor based on a term's document frequency (the number
of documents which contain the term). This value is multiplied by the
tf(int)
factor for each term in the query and these products are
then summed to form the initial score for a document.
Terms that occur in fewer documents are better indicators of topic, so implementations of this method usually return larger values for rare terms, and smaller values for common terms.
docFreq  the number of documents which contain the term 

numDocs  the total number of documents in the collection 
Computes a score factor for a phrase.
The default implementation sums the idf factor for each term in the phrase.
terms  the terms in the phrase 

searcher  the document collection being searched 
IOException 

Computes a score factor for a simple term and returns an explanation for that score factor.
The default implementation uses:
idf(searcher.docFreq(term), searcher.maxDoc());Note that
maxDoc()
is used instead of
IndexReader#numDocs()
because also
docFreq(Term)
is used, and when the latter
is inaccurate, so is maxDoc()
, and in the same direction.
In addition, maxDoc()
is more efficient to computeterm  the term in question 

searcher  the document collection being searched 
IOException 

Computes the normalization value for a field given the total number of terms contained in a field. These values, together with field boosts, are stored in an index and multipled into scores for hits on each field by the search code.
Matches in longer fields are less precise, so implementations of this
method usually return smaller values when numTokens
is large,
and larger values when numTokens
is small.
Note that the return values are computed under
addDocument(org.apache.lucene.document.Document)
and then stored using
encodeNorm(float)
.
Thus they have limited precision, and documents
must be reindexed if this method is altered.
fieldName  the name of the field 

numTokens  the total number of tokens contained in fields named fieldName of doc. 
Computes the normalization value for a query given the sum of the squared weights of each of the query terms. This value is multiplied into the weight of each query term. While the classic query normalization factor is computed as 1/sqrt(sumOfSquaredWeights), other implementations might completely ignore sumOfSquaredWeights (ie return 1).
This does not affect ranking, but the default implementation does make scores from different queries more comparable than they would be by eliminating the magnitude of the Query vector as a factor in the score.
sumOfSquaredWeights  the sum of the squares of query term weights 

Calculate a scoring factor based on the data in the payload. Overriding implementations are responsible for interpreting what is in the payload. Lucene makes no assumptions about what is in the byte array.
The default implementation returns 1.
docId  The docId currently being scored. If this value is NO_DOC_ID_PROVIDED , then it should be assumed that the PayloadQuery implementation does not provide document information 

fieldName  The fieldName of the term this payload belongs to 
start  The start position of the payload 
end  The end position of the payload 
payload  The payload byte array to be scored 
offset  The offset into the payload array 
length  The length in the array 
Set the default Similarity implementation used by indexing and search code.
Computes the amount of a sloppy phrase match, based on an edit distance.
This value is summed for each sloppy phrase match in a document to form
the frequency that is passed to tf(float)
.
A phrase match with a small edit distance to a document passage more closely matches the document, so implementations of this method usually return larger values when the edit distance is small and smaller values when it is large.
distance  the edit distance of this sloppy phrase match 

Computes a score factor based on a term or phrase's frequency in a
document. This value is multiplied by the idf(int, int)
factor for each term in the query and these products are then summed to
form the initial score for a document.
Terms and phrases repeated in a document indicate the topic of the
document, so implementations of this method usually return larger values
when freq
is large, and smaller values when freq
is small.
freq  the frequency of a term within a document 

Computes a score factor based on a term or phrase's frequency in a
document. This value is multiplied by the idf(int, int)
factor for each term in the query and these products are then summed to
form the initial score for a document.
Terms and phrases repeated in a document indicate the topic of the
document, so implementations of this method usually return larger values
when freq
is large, and smaller values when freq
is small.
The default implementation calls tf(float)
.
freq  the frequency of a term within a document 
