Code to search indices.

See: Description

Package Description

Code to search indices.

Table Of Contents

  1. Search Basics
  2. The Query Classes
  3. Changing the Scoring


Search over indices. Applications usually call,int) or,Filter,int).

Query Classes











Another common search is to find documents containing certain phrases. This is handled two different ways:




The TermRangeQuery matches all documents that occur in the exclusive range of a lower Term and an upper Term. according to String.compareTo(String). It is not intended for numerical ranges, use NumericRangeQuery instead. For example, one could find all documents that have terms beginning with the letters a through c. This type of Query is frequently used to find documents that occur in a specific date range.


The NumericRangeQuery matches all documents that occur in a numeric range. For NumericRangeQuery to work, you must index the values using a special NumericField.

PrefixQuery, WildcardQuery

While the PrefixQuery has a different implementation, it is essentially a special case of the WildcardQuery. The PrefixQuery allows an application to identify all documents with terms that begin with a certain string. The WildcardQuery generalizes this by allowing for the use of * (matches 0 or more characters) and ? (matches exactly one character) wildcards. Note that the WildcardQuery can be quite slow. Also note that WildcardQuery should not start with * and ?, as these are extremely slow. To remove this protection and allow a wildcard at the beginning of a term, see method setAllowLeadingWildcard in QueryParser.



Changing Similarity



To make this change, implement your own Similarity (likely you'll want to simply subclass DefaultSimilarity) and then use the new class by calling IndexWriter.setSimilarity before indexing and Searcher.setSimilarity before searching.






Changing Scoring — Expert Level

Changing scoring is an expert level task, so tread carefully and be prepared to share your code if you want help.

With the warning out of the way, it is possible to change a lot more than just the Similarity when it comes to scoring in Lucene. Lucene's scoring is a complex mechanism that is grounded by three main classes:


The Query Class


  2. rewrite(IndexReader reader) — Rewrites queries into primitive queries. Primitive queries are: TermQuery, BooleanQuery, and other queries that implement Query.html#createWeight(Searcher searcher)

The Weight Interface

The Weight interface provides an internal representation of the Query so that it can be reused. Any Searcher dependent state should be stored in the Weight implementation, not in the Query class. The interface defines six methods that must be implemented:

  1. Weight#getQuery() — Pointer to the Query that this Weight represents.
  2. Weight#getValue() — The weight for this Query. For example, the TermQuery.TermWeight value is equal to the idf^2 * boost * queryNorm
  3. Weight#sumOfSquaredWeights() — The sum of squared weights. For TermQuery, this is (idf * boost)^2
  4. Weight#normalize(float) — Determine the query normalization factor. The query normalization may allow for comparing scores between queries.
  5. Weight#scorer(IndexReader, boolean, boolean) — Construct a new Scorer for this Weight. See The Scorer Class below for help defining a Scorer. As the name implies, the Scorer is responsible for doing the actual scoring of documents given the Query.
  6. Weight#explain(Searcher, IndexReader, int) — Provide a means for explaining why a given document was scored the way it was.

The Scorer Class


  1. DocIdSetIterator#nextDoc() — Advances to the next document that matches this Query, returning true if and only if there is another document that matches.
  2. DocIdSetIterator#docID() — Returns the id of the Document that contains the match. It is not valid until next() has been called at least once.
  3. Scorer#score(Collector) — Scores and collects all matching documents using the given Collector.
  4. Scorer#score() — Return the score of the current document. This value can be determined in any appropriate way for an application. For instance, the TermScorer returns the tf * Weight.getValue() * fieldNorm.

Why would I want to add my own Query?
