Preface:
Every time a document matches during search, it’s assigned a score that reflects how good the match is. This score computes how similar the document is to the query, with higher scores reflecting stronger similarity and thus stronger matches. We chose to discuss this complex topic early in this chapter so you’ll have a general sense of the various factors that go into Lucene scoring as you continue to read. We’ll start with details on Lucene’s scoring formula, and then show how you can see the full explanation of how a certain document arrived at its score.
How Lucene scores:
Without further ado, meet Lucene’s similarity scoring formula, shown in figure 3.3. It’s called the similarity scoring formula because its purpose is to measure the similarity between a query and each document that matches the query. The score is computed for each document (d) matching each term (t) in a query (q):
This score is the raw score, which is a floating-point number >= 0.0. Typically, if an application presents the score to the end user, it’s best to first normalize the scores by dividing all scores by the maximum score for the query. The larger the similarity score, the better the match of the document to the query. By default Lucene returns documents reverse-sorted by this score, meaning the top documents are the best matching ones. Table 3.5 describes each of the factors in the scoring formula.
Boost factors are built into the equation to let you affect a query or field’s influence on score. Field boosts come in explicitly in the equation as the boost(t.field in d)factor, set at indexing time. The default value of field boosts, logically, is 1.0. During indexing, a document can be assigned a boost, too. A document boost factor implicitly sets the starting field boost of all fields to the specified value. Field-specific boosts are multiplied by the starting value, giving the final value of the field boost factor. It’s possible to add the same named field to a document multiple times, and in such situations the field boost is computed as all the boosts specified for that field and document multiplied together.
In addition to the explicit factors in this equation, other factors can be computed on a per-query basis as part of the queryNorm factor. Queries themselves can have an impact on the document score. Boosting a Query instance is sensible only in a multiple-clause query; if only a single term is used for searching, changing its boost would impact all matched documents equally. In a multiple-clause Boolean query, some documents may match one clause but not another, enabling the boost factor to discriminate between matching documents. Queries also default to a 1.0 boost factor.
Most of these scoring formula factors are controlled and implemented as a subclass of the abstract Similarity class. DefaultSimilarity is the implementation used unless otherwise specified. More computations are performed under the covers of DefaultSimilarity; for example, the term frequency factor is the square root of the actual frequency. In practice, it’s extremely rare to need a change in these factors. Should you need to change them, please refer to Similarity’s Javadocs, and be prepared with a solid understanding of these factors and the effect your changes will have.
Using explain() to understand hit scoring:
Whew! The scoring formula seems daunting—and it is. We’re talking about factors that rank one document higher than another based on a query; that in and of itself deserves the sophistication going on. If you want to see how all these factors play out, Lucene provides a helpful feature called Explanation. IndexSearcher has anexplain method, which requires a Query and a document ID and returns an Explanation object.
The Explanation object internally contains all the gory details that factor into the score calculation. Each detail can be accessed individually if you like; but generally, dumping out the explanation in its entirety is desired. The .toString() method dumps a nicely formatted text representation of the Explanations. We wrote a simple program to dump Explanations, shown in listing 3.4.
- Listing 3.4 The explain() method
Then we can use below sample code to test it (You may run example from Ch3. Adding search - Implementing a simple search feature to do index in first):
The output result will look like:
Every time a document matches during search, it’s assigned a score that reflects how good the match is. This score computes how similar the document is to the query, with higher scores reflecting stronger similarity and thus stronger matches. We chose to discuss this complex topic early in this chapter so you’ll have a general sense of the various factors that go into Lucene scoring as you continue to read. We’ll start with details on Lucene’s scoring formula, and then show how you can see the full explanation of how a certain document arrived at its score.
How Lucene scores:
Without further ado, meet Lucene’s similarity scoring formula, shown in figure 3.3. It’s called the similarity scoring formula because its purpose is to measure the similarity between a query and each document that matches the query. The score is computed for each document (d) matching each term (t) in a query (q):
This score is the raw score, which is a floating-point number >= 0.0. Typically, if an application presents the score to the end user, it’s best to first normalize the scores by dividing all scores by the maximum score for the query. The larger the similarity score, the better the match of the document to the query. By default Lucene returns documents reverse-sorted by this score, meaning the top documents are the best matching ones. Table 3.5 describes each of the factors in the scoring formula.
Boost factors are built into the equation to let you affect a query or field’s influence on score. Field boosts come in explicitly in the equation as the boost(t.field in d)factor, set at indexing time. The default value of field boosts, logically, is 1.0. During indexing, a document can be assigned a boost, too. A document boost factor implicitly sets the starting field boost of all fields to the specified value. Field-specific boosts are multiplied by the starting value, giving the final value of the field boost factor. It’s possible to add the same named field to a document multiple times, and in such situations the field boost is computed as all the boosts specified for that field and document multiplied together.
In addition to the explicit factors in this equation, other factors can be computed on a per-query basis as part of the queryNorm factor. Queries themselves can have an impact on the document score. Boosting a Query instance is sensible only in a multiple-clause query; if only a single term is used for searching, changing its boost would impact all matched documents equally. In a multiple-clause Boolean query, some documents may match one clause but not another, enabling the boost factor to discriminate between matching documents. Queries also default to a 1.0 boost factor.
Most of these scoring formula factors are controlled and implemented as a subclass of the abstract Similarity class. DefaultSimilarity is the implementation used unless otherwise specified. More computations are performed under the covers of DefaultSimilarity; for example, the term frequency factor is the square root of the actual frequency. In practice, it’s extremely rare to need a change in these factors. Should you need to change them, please refer to Similarity’s Javadocs, and be prepared with a solid understanding of these factors and the effect your changes will have.
Using explain() to understand hit scoring:
Whew! The scoring formula seems daunting—and it is. We’re talking about factors that rank one document higher than another based on a query; that in and of itself deserves the sophistication going on. If you want to see how all these factors play out, Lucene provides a helpful feature called Explanation. IndexSearcher has anexplain method, which requires a Query and a document ID and returns an Explanation object.
The Explanation object internally contains all the gory details that factor into the score calculation. Each detail can be accessed individually if you like; but generally, dumping out the explanation in its entirety is desired. The .toString() method dumps a nicely formatted text representation of the Explanations. We wrote a simple program to dump Explanations, shown in listing 3.4.
- Listing 3.4 The explain() method
- package ch3;
- import java.io.File;
- import java.io.IOException;
- import junit.framework.TestCase;
- import org.apache.lucene.analysis.Analyzer;
- import org.apache.lucene.analysis.SimpleAnalyzer;
- import org.apache.lucene.analysis.standard.StandardAnalyzer;
- import org.apache.lucene.document.Document;
- import org.apache.lucene.document.Field;
- import org.apache.lucene.index.IndexReader;
- import org.apache.lucene.index.IndexWriter;
- import org.apache.lucene.index.IndexWriterConfig;
- import org.apache.lucene.index.Term;
- import org.apache.lucene.queryParser.QueryParser;
- import org.apache.lucene.search.IndexSearcher;
- import org.apache.lucene.search.Query;
- import org.apache.lucene.search.TermQuery;
- import org.apache.lucene.search.TopDocs;
- import org.apache.lucene.store.Directory;
- import org.apache.lucene.store.FSDirectory;
- import org.apache.lucene.util.Version;
- public class ListExams extends TestCase{
- public static Version LUCENE_VERSION = Version.LUCENE_30;
- public Directory directory = null;
- public IndexSearcher searcher = null;
- public File indexpath = new File("./test");
- protected String[] ids = { "1", "2" };
- protected String[] unindexed = { "Ant in Action", "Junit in Action" };
- protected String[] unstored = { "Amsterdam has lots of bridges",
- "Venice has lots of canals" };
- protected String[] subject = { "Ant in Action with Junit", "JUnit in Action, Second Edition" };
- @Override
- protected void tearDown() throws Exception
- {
- //System.out.printf("\t[Test] tearDown...\n");
- searcher.close();
- directory.close();
- searcher = null;
- /*Thread.sleep(1000);
- File fs[] = indexpath.listFiles();
- for(File f:fs)
- {
- System.out.printf("\t[Test] Delete %s...\n", f.getAbsolutePath());
- f.delete();
- }
- Thread.sleep(1000);*/
- }
- @Override
- protected void setUp() throws Exception {
- //System.out.printf("\t[Test] setUp...\n");
- // 1) Run before every test
- directory = FSDirectory.open(indexpath);
- buildIndex();
- }
- protected void buildIndex() throws Exception
- {
- // 2) Cretae IndexWriter
- IndexWriter writer = getWriter();
- // 3) Add document
- for (int i = 0; i < ids.length; i++) {
- Document doc = new Document();
- doc.add(new Field("id", ids[i], Field.Store.YES,
- Field.Index.NOT_ANALYZED));
- doc.add(new Field("title", unindexed[i], Field.Store.YES,
- Field.Index.NO));
- doc.add(new Field("contents", unstored[i], Field.Store.NO,
- Field.Index.ANALYZED));
- doc.add(new Field("subject", subject[i], Field.Store.YES,
- Field.Index.ANALYZED));
- writer.addDocument(doc);
- }
- writer.commit();
- writer.close();
- }
- /**
- * BD: The StandardAnalyzer applies a LowerCaseFilter that would make search insensitive.
- * Reference:
- * - How to make lucene be case-insensitive
- * http://stackoverflow.com/questions/5512803/how-to-make-lucene-be-case-insensitive
- * @return
- * @throws IOException
- */
- private IndexWriter getWriter() throws IOException {
- Analyzer alyz = new StandardAnalyzer(LUCENE_VERSION);
- IndexWriterConfig iwConfig = new IndexWriterConfig(LUCENE_VERSION, alyz);
- iwConfig.setOpenMode(IndexWriterConfig.OpenMode.CREATE);
- return new IndexWriter(directory, iwConfig);
- }
- private IndexSearcher getSearcher() throws IOException
- {
- if(searcher==null)
- {
- IndexReader idxReader = IndexReader.open(directory);
- searcher = new IndexSearcher(idxReader);
- }
- return searcher;
- }
- /**
- * BD: List 3.1
- * @throws Exception
- */
- public void testTerm() throws Exception {
- // 1) Create IndexSearcher -> directory is built during setUp()
- IndexSearcher searcher = getSearcher();
- // 2) Build Single Term Query
- Term t = new Term("subject", "ant");
- Query query = new TermQuery(t);
- // 3) Search
- TopDocs docs = searcher.search(query, 10);
- // 4) Confirm one hit for 'ant' query.
- assertEquals("Ant in Action", 1, docs.totalHits);
- // 5) Search again
- t = new Term("subject", "junit");
- docs = searcher.search(new TermQuery(t), 10);
- // 6) Confirm two hit for 'junit' query.
- assertEquals("Ant in Action, " + "JUnit in Action, Second Edition",
- 2, docs.totalHits);
- // 7) Close searcher and directory.
- }
- /**
- * BD: List 3.2 - QueryParser, which makes it trivial to translate search text into a Query
- * @throws Exception
- */
- public void testQueryParser() throws Exception {
- // 1) Create IndexSearcher -> directory is built during setUp()
- IndexSearcher searcher = getSearcher();
- // 2) Create QueryParser
- QueryParser parser = new QueryParser(LUCENE_VERSION, "subject",
- new SimpleAnalyzer(LUCENE_VERSION));
- // 3) Query subject to have "JUNIT", "ANT" but without "MOCK";
- Query query = parser.parse("+JUNIT +ANT -MOCK");
- TopDocs docs = searcher.search(query, 10);
- // 4) Assert to have 1 hit.
- assertEquals(1, docs.totalHits);
- // 5) Fetch the top1 document from search result.
- Document d = searcher.doc(docs.scoreDocs[0].doc);
- // 6) Assert its title to be "Ant in Action".
- assertEquals("Ant in Action", d.get("title"));
- // 7) Query again to have "mock" or "junit"
- query = parser.parse("mock OR junit");
- docs = searcher.search(query, 10);
- // 8) Assert to have 2 hit.
- assertEquals("Ant in Action, " + "JUnit in Action, Second Edition", 2,
- docs.totalHits);
- // 9) Close searcher and directory in tearDown()
- }
- }
- File indexpath = new File("./test"); /*Index folder*/
- String arg_set[] = {indexpath.getAbsolutePath(), "ant"}; /*Query term='ant'*/
- Explainer.main(arg_set);
